Merge pull request #1423 from spotify/bil/techdocs-add-python-formatter

techdocs: add python formatter to techdocs-core python package
2020-06-24 11:01:04 +02:00
parent 38a63c4472 b53ecbff3e
commit 921873e0b8
7 changed files with 92 additions and 36 deletions
@@ -6,8 +6,10 @@ Welcome to MkDocs. This is the TechDocs implementation of MkDocs.

 ## Getting started

-```
-  docker build ./container -t mkdocs-container
+```bash
+docker build ./container -t mkdocs-container

-  docker run -w /content -v $(pwd)/mock-docs:/content -p 8000:8000 -it mkdocs-container serve -a 0.0.0.0:8000
+docker run -w /content -v $(pwd)/mock-docs:/content -p 8000:8000 -it mkdocs-container serve -a 0.0.0.0:8000
 ```
+
+Then open up `http://localhost:8000` on your local machine.
@@ -1,17 +1,16 @@
-
-#   Copyright 2020 Spotify AB
+# Copyright 2020 Spotify AB
 #  
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #  
-#       http://www.apache.org/licenses/LICENSE-2.0
+#     http://www.apache.org/licenses/LICENSE-2.0
 #  
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

 FROM python:3.7.7-alpine3.12

@@ -0,0 +1,2 @@
+.tox
+*.egg-info
@@ -0,0 +1,45 @@
+# 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
+
+```bash
+pip install -r requirements.txt
+python -m black src/
+```
+
+**Note:** This will write to all Python files in `src/` with the formatted code. If you would like to only check to see if it passes, simply append the `--check` flag.
@@ -1 +1,9 @@
+# The "base" version of the Mkdocs project.
+# Note: if you update this, also update `install_requires` in setup.py
+# https://github.com/mkdocs/mkdocs
 mkdocs==1.1.2
+
+# The linter using for Python
+# Note: This requires Python 3.6+ to run, but can format Python 2 code too.
+# https://github.com/psf/black
+black==19.10b0
@@ -1,17 +1,17 @@
 """
- * Copyright 2020 Spotify AB
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+Copyright 2020 Spotify AB
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
 """
 from setuptools import setup, find_packages

@@ -19,17 +19,17 @@ from mkdocs.theme import Theme

 from mkdocs.contrib.search import SearchPlugin

+
 class TechDocsCore(BasePlugin):
    def on_config(self, config):
-       # Theme
-       config['theme'] = Theme(name="material")
+        # Theme
+        config["theme"] = Theme(name="material")

-       # Plugins
-       del config['plugins']['techdocs-core']
+        # Plugins
+        del config["plugins"]["techdocs-core"]

-       search_plugin = SearchPlugin()
-       search_plugin.load_config({})
-       config['plugins']['search'] = search_plugin
-
-       return config
+        search_plugin = SearchPlugin()
+        search_plugin.load_config({})
+        config["plugins"]["search"] = search_plugin

+        return config