From cddfe9bd58aa668f7cfe65fa42a8c51f446c4e4c Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:11:16 +0200 Subject: [PATCH 01/10] feat(techdocs-core): add python formatter --- .../mkdocs/container/techdocs-core/requirements.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/requirements.txt b/plugins/techdocs/mkdocs/container/techdocs-core/requirements.txt index b3667f94ec..2a13d1a9da 100644 --- a/plugins/techdocs/mkdocs/container/techdocs-core/requirements.txt +++ b/plugins/techdocs/mkdocs/container/techdocs-core/requirements.txt @@ -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 From 3f79513fdd359b68c0b8687a00f9d7780907e87b Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:16:36 +0200 Subject: [PATCH 02/10] chore(techdocs-core): lower indentation of notice --- plugins/techdocs/mkdocs/container/Dockerfile | 20 +++++++------- .../mkdocs/container/techdocs-core/setup.py | 26 +++++++++---------- 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/plugins/techdocs/mkdocs/container/Dockerfile b/plugins/techdocs/mkdocs/container/Dockerfile index 1ae66589b6..ce54f53983 100644 --- a/plugins/techdocs/mkdocs/container/Dockerfile +++ b/plugins/techdocs/mkdocs/container/Dockerfile @@ -1,17 +1,17 @@ -# 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 diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/setup.py b/plugins/techdocs/mkdocs/container/techdocs-core/setup.py index faa8b8c46e..a259ae0615 100644 --- a/plugins/techdocs/mkdocs/container/techdocs-core/setup.py +++ b/plugins/techdocs/mkdocs/container/techdocs-core/setup.py @@ -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 From 8f91501b07aaba6eab12c5b1352d0edcb159c785 Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:14:09 +0200 Subject: [PATCH 03/10] chore(mkdocs/container): remove initial newline --- plugins/techdocs/mkdocs/container/Dockerfile | 1 - 1 file changed, 1 deletion(-) diff --git a/plugins/techdocs/mkdocs/container/Dockerfile b/plugins/techdocs/mkdocs/container/Dockerfile index ce54f53983..8df86eadb0 100644 --- a/plugins/techdocs/mkdocs/container/Dockerfile +++ b/plugins/techdocs/mkdocs/container/Dockerfile @@ -1,4 +1,3 @@ - # Copyright 2020 Spotify AB # # Licensed under the Apache License, Version 2.0 (the "License"); From 97e9e325e54c800c1a8f4f18972c88bd400cb32a Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:31:07 +0200 Subject: [PATCH 04/10] docs(techdocs-core): add README --- .../mkdocs/container/techdocs-core/README.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 plugins/techdocs/mkdocs/container/techdocs-core/README.md diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/README.md b/plugins/techdocs/mkdocs/container/techdocs-core/README.md new file mode 100644 index 0000000000..04606088d4 --- /dev/null +++ b/plugins/techdocs/mkdocs/container/techdocs-core/README.md @@ -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. From 4c6ea359602be1223aa7320c5f3574cd0c8c7c07 Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:32:23 +0200 Subject: [PATCH 05/10] chore(techdocs-core): added gitignore --- plugins/techdocs/mkdocs/container/techdocs-core/.gitignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 plugins/techdocs/mkdocs/container/techdocs-core/.gitignore diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/.gitignore b/plugins/techdocs/mkdocs/container/techdocs-core/.gitignore new file mode 100644 index 0000000000..cd5c4a44f3 --- /dev/null +++ b/plugins/techdocs/mkdocs/container/techdocs-core/.gitignore @@ -0,0 +1,2 @@ +.tox +*.egg-info From d6cf8892fe19fe009cc7698c7c0ce0b7ff5bac27 Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:33:29 +0200 Subject: [PATCH 06/10] docs(techdocs-core): added dependency install command --- plugins/techdocs/mkdocs/container/techdocs-core/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/README.md b/plugins/techdocs/mkdocs/container/techdocs-core/README.md index 04606088d4..b4a32a57cb 100644 --- a/plugins/techdocs/mkdocs/container/techdocs-core/README.md +++ b/plugins/techdocs/mkdocs/container/techdocs-core/README.md @@ -37,10 +37,11 @@ See the `README.md` located in the `mkdocs/` folder for more details on how to b ## Linting and Tests -To run the tests, you'll need `tox` installed: +To run the tests, you'll need `tox` installed with our dependencies installed: ```bash pip install tox +pip install -r requirements.txt tox ``` From f9ee9991a05a98535fea4680328edb274abbfaa6 Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:45:22 +0200 Subject: [PATCH 07/10] docs(techdocs-core): added linting section --- .../techdocs/mkdocs/container/techdocs-core/README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/README.md b/plugins/techdocs/mkdocs/container/techdocs-core/README.md index b4a32a57cb..143acf3c3b 100644 --- a/plugins/techdocs/mkdocs/container/techdocs-core/README.md +++ b/plugins/techdocs/mkdocs/container/techdocs-core/README.md @@ -35,14 +35,11 @@ In the parent `Dockerfile` we add this folder to the build and install the packa 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 with our dependencies installed: +## Linting ```bash -pip install tox pip install -r requirements.txt -tox +python -m black src/ ``` -This will invoke our linter and tests. You can configure this by editing the `tox.ini` folder located in this folder. +**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. From f432c9deb6a41b7e8ff82113cbee8747b4a56ace Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:45:39 +0200 Subject: [PATCH 08/10] chore(techdocs-core): formatted all files in src/ --- .../mkdocs/container/techdocs-core/src/core.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/plugins/techdocs/mkdocs/container/techdocs-core/src/core.py b/plugins/techdocs/mkdocs/container/techdocs-core/src/core.py index e42a60d28b..7fce7d6dac 100644 --- a/plugins/techdocs/mkdocs/container/techdocs-core/src/core.py +++ b/plugins/techdocs/mkdocs/container/techdocs-core/src/core.py @@ -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 From 464e07d067052c34fd94e85d2c6701414bb7991c Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:51:22 +0200 Subject: [PATCH 09/10] docs(mkdocs): lower indentation for container setup commands --- plugins/techdocs/mkdocs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/techdocs/mkdocs/README.md b/plugins/techdocs/mkdocs/README.md index 4d1c11d7b0..8cf1717cf1 100644 --- a/plugins/techdocs/mkdocs/README.md +++ b/plugins/techdocs/mkdocs/README.md @@ -6,8 +6,8 @@ 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 ``` From b53ecbff3ed45efe9be5a639ca5edb66e91bc55a Mon Sep 17 00:00:00 2001 From: Bilawal Hameed Date: Tue, 23 Jun 2020 20:52:04 +0200 Subject: [PATCH 10/10] docs(mkdocs): added open up localhost:3000 to readme --- plugins/techdocs/mkdocs/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/plugins/techdocs/mkdocs/README.md b/plugins/techdocs/mkdocs/README.md index 8cf1717cf1..5c2a7725aa 100644 --- a/plugins/techdocs/mkdocs/README.md +++ b/plugins/techdocs/mkdocs/README.md @@ -11,3 +11,5 @@ 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 ``` + +Then open up `http://localhost:8000` on your local machine.