docs(techdocs-core): add README

2020-06-23 20:31:07 +02:00
parent 8f91501b07
commit 97e9e325e5
1 changed files with 47 additions and 0 deletions
@@ -0,0 +1,47 @@
+# techdocs-core
+
+This is the base [Mkdocs](https://mkdocs.org) plugin used when using Mkdocs with Spotify's TechDocs. It is written in Python and packages all of our Mkdocs defaults, such as theming, plugins, etc in a single plugin.
+
+## Usage
+
+**Installation instructions TBD.** We haven't published it to a Python registry yet.
+
+Once you have installed the `mkdocs-techdocs-core` plugin, you'll need to add it to your `mkdocs.yml`.
+
+```yaml
+site_name: Backstage Docs
+
+nav:
+  - Home: index.md
+  - Developing a Plugin: developing-a-plugin.md
+
+plugins:
+  - techdocs-core
+```
+
+## Running Locally
+
+You can install this package locally using `pip` and the `--editable` flag used for making developing Python packages.
+
+```bash
+pip install --editable .
+```
+
+You'll then have the `techdocs-core` package available to use in Mkdocs and `pip` will point the dependency to this folder.
+
+## Running with Docker
+
+In the parent `Dockerfile` we add this folder to the build and install the package locally in the container. In the future, we'll probably move away from this approach and have it download directly from a Python registry (and this folder will publish to one).
+
+See the `README.md` located in the `mkdocs/` folder for more details on how to build and run the Docker container.
+
+## Linting and Tests
+
+To run the tests, you'll need `tox` installed:
+
+```bash
+pip install tox
+tox
+```
+
+This will invoke our linter and tests. You can configure this by editing the `tox.ini` folder located in this folder.