From b8e67816c95ce10b13d55cfa562545f8c5294a5a Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 3 Nov 2020 11:45:43 +0100 Subject: [PATCH 1/4] Remove mkdocs-techdocs-core from backstage mono-repo New home: https://github.com/backstage/mkdocs-techdocs-core --- docs/features/techdocs/concepts.md | 2 +- .../techdocs-core/.gitignore | 2 - .../techdocs-core/README.md | 149 ------------------ .../techdocs-core/requirements.txt | 16 -- .../techdocs-container/techdocs-core/setup.py | 57 ------- .../techdocs-core/src/__init__.py | 0 .../techdocs-core/src/core.py | 105 ------------ .../techdocs-core/src/test_core.py | 41 ----- 8 files changed, 1 insertion(+), 371 deletions(-) delete mode 100644 packages/techdocs-container/techdocs-core/.gitignore delete mode 100644 packages/techdocs-container/techdocs-core/README.md delete mode 100644 packages/techdocs-container/techdocs-core/requirements.txt delete mode 100644 packages/techdocs-container/techdocs-core/setup.py delete mode 100644 packages/techdocs-container/techdocs-core/src/__init__.py delete mode 100644 packages/techdocs-container/techdocs-core/src/core.py delete mode 100644 packages/techdocs-container/techdocs-core/src/test_core.py diff --git a/docs/features/techdocs/concepts.md b/docs/features/techdocs/concepts.md index 13b780524b..ed1fc2220c 100644 --- a/docs/features/techdocs/concepts.md +++ b/docs/features/techdocs/concepts.md @@ -14,7 +14,7 @@ The TechDocs Core Plugin is an [MkDocs](https://www.mkdocs.org/) plugin created as a wrapper around multiple MkDocs plugins and Python Markdown extensions to standardize the configuration of MkDocs used for TechDocs. -[TechDocs Core](https://github.com/backstage/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md) +[TechDocs Core](https://github.com/backstage/mkdocs-techdocs-core) ### TechDocs container diff --git a/packages/techdocs-container/techdocs-core/.gitignore b/packages/techdocs-container/techdocs-core/.gitignore deleted file mode 100644 index cd5c4a44f3..0000000000 --- a/packages/techdocs-container/techdocs-core/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -.tox -*.egg-info diff --git a/packages/techdocs-container/techdocs-core/README.md b/packages/techdocs-container/techdocs-core/README.md deleted file mode 100644 index 7bd6fe4187..0000000000 --- a/packages/techdocs-container/techdocs-core/README.md +++ /dev/null @@ -1,149 +0,0 @@ -# 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. - -[Python Package](https://pypi.org/project/mkdocs-techdocs-core/) - -## Usage - -```bash -$ pip install mkdocs-techdocs-core -``` - -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 `techdocs-container/` 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. - -## MkDocs plugins and extensions - -The TechDocs Core MkDocs plugin comes with a set of extensions and plugins that mkdocs supports. Below you can find a list of all extensions and plugins that are included in the -TechDocs Core plugin: - -Plugins: - -- [search](https://www.mkdocs.org/user-guide/configuration/#search) -- [mkdocs-monorepo-plugin](https://github.com/spotify/mkdocs-monorepo-plugin) - -Extensions: - -- [admonition](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#admonitions) -- [toc](https://python-markdown.github.io/extensions/toc/) -- [pymdown](https://facelessuser.github.io/pymdown-extensions/) - - caret - - critic - - details - - emoji - - superfences - - inlinehilite - - magiclink - - mark - - smartsymobls - - highlight - - extra - - tabbed - - tasklist - - tilde -- [markdown_inline_graphviz](https://pypi.org/project/markdown-inline-graphviz/) -- [plantuml_markdown](https://pypi.org/project/plantuml-markdown/) - -## Changelog - -### 0.0.11 - -- Any MkDocs plugin configurations from mkdocs.yml will now work and override the default configuration. See https://github.com/spotify/backstage/issues/3017 - -### 0.0.10 - -- Pin Markdown version to fix issue with Graphviz - -### 0.0.9 - -- Change development status to 3 - Alpha - -### 0.0.8 - -- Superfences and Codehilite doesn't work very well together (squidfunk/mkdocs-material#1604) so therefore the codehilite extension is replaced by pymdownx.highlight - -* Uses pymdownx extensions v.7.1 instead of 8.0.0 to allow legacy_tab_classes config. This makes the techdocs core plugin compatible with the usage of tabs for grouping markdown with the following syntax: - -```` - ```java tab="java 2" - public void function() { - .... - } - ``` -```` - -as well as the new - -```` - === "Java" - - ```java - public void function() { - .... - } - ``` -```` - -The pymdownx extension will be bumped too 8.0.0 in the near future. - -- pymdownx.tabbed is added to support tabs to group markdown content, such as codeblocks. - -- "PyMdown Extensions includes three extensions that are meant to replace their counterpart in the default Python Markdown extensions." Therefore some extensions has been taken away in this version that comes by default from pymdownx.extra which is added now (https://facelessuser.github.io/pymdown-extensions/usage_notes/#incompatible-extensions) - -### 0.0.7 - -- Fix an issue with configuration of emoji support - -### 0.0.6 - -- Further adjustments to versions to find ones that are compatible - -### 0.0.5 - -- Downgrade some versions of markdown extensions to versions that are more stable - -### 0.0.4 - -- Added support for more mkdocs extensions - - mkdocs-material - - mkdocs-monorepo-plugin - - plantuml-markdown - - markdown_inline_graphviz_extension - - pygments - - pymdown-extensions diff --git a/packages/techdocs-container/techdocs-core/requirements.txt b/packages/techdocs-container/techdocs-core/requirements.txt deleted file mode 100644 index fc56ae6aee..0000000000 --- a/packages/techdocs-container/techdocs-core/requirements.txt +++ /dev/null @@ -1,16 +0,0 @@ -# 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 -mkdocs-material==5.3.2 -mkdocs-monorepo-plugin==0.4.5 -plantuml-markdown==3.1.2 -markdown_inline_graphviz_extension==1.1 -pygments==2.6.1 -pymdown-extensions==7.1 -Markdown==3.2.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 diff --git a/packages/techdocs-container/techdocs-core/setup.py b/packages/techdocs-container/techdocs-core/setup.py deleted file mode 100644 index bc3e6c7082..0000000000 --- a/packages/techdocs-container/techdocs-core/setup.py +++ /dev/null @@ -1,57 +0,0 @@ -""" -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 os import path - -# read the contents of the README file in the current directory -this_dir = path.abspath(path.dirname(__file__)) -with open(path.join(this_dir, "README.md"), encoding="utf-8") as file: - long_description = file.read() - -setup( - name="mkdocs-techdocs-core", - version="0.0.11", - description="A Mkdocs package that contains TechDocs defaults", - long_description=long_description, - long_description_content_type="text/markdown", - keywords="mkdocs", - url="https://github.com/backstage/backstage", - author="TechDocs Core", - author_email="pulp-fiction@spotify.com", - license="Apache-2.0", - python_requires=">=3.7", - install_requires=[ - "mkdocs>=1.1.2", - "mkdocs-material==5.3.2", - "mkdocs-monorepo-plugin==0.4.5", - "plantuml-markdown==3.1.2", - "markdown_inline_graphviz_extension==1.1", - "pygments==2.6.1", - "pymdown-extensions==7.1", - "Markdown==3.2.2", - ], - classifiers=[ - "Development Status :: 3 - Alpha", - "Intended Audience :: Developers", - "Intended Audience :: Information Technology", - "License :: OSI Approved :: Apache Software License", - "Programming Language :: Python", - "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.7", - ], - packages=find_packages(), - entry_points={"mkdocs.plugins": ["techdocs-core = src.core:TechDocsCore"]}, -) diff --git a/packages/techdocs-container/techdocs-core/src/__init__.py b/packages/techdocs-container/techdocs-core/src/__init__.py deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/packages/techdocs-container/techdocs-core/src/core.py b/packages/techdocs-container/techdocs-core/src/core.py deleted file mode 100644 index 7d32b69ad8..0000000000 --- a/packages/techdocs-container/techdocs-core/src/core.py +++ /dev/null @@ -1,105 +0,0 @@ -""" - * 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 mkdocs.plugins import BasePlugin -from mkdocs.theme import Theme -from mkdocs.contrib.search import SearchPlugin -from mkdocs_monorepo_plugin.plugin import MonorepoPlugin -from pymdownx.emoji import to_svg -import tempfile -import os - - -class TechDocsCore(BasePlugin): - def on_config(self, config): - fp = open(os.path.join(tempfile.gettempdir(), "techdocs_metadata.json"), "w+") - fp.write( - '{\n "site_name": "{{ config.site_name }}",\n "site_description": "{{ config.site_description }}"\n}' - ) - - mdx_configs_override = {} - if "mdx_configs" in config: - mdx_configs_override = config["mdx_configs"].copy() - - # Theme - config["theme"] = Theme( - name="material", static_templates=["techdocs_metadata.json",], - ) - config["theme"].dirs.append(tempfile.gettempdir()) - - # Plugins - del config["plugins"]["techdocs-core"] - - search_plugin = SearchPlugin() - search_plugin.load_config({}) - - monorepo_plugin = MonorepoPlugin() - monorepo_plugin.load_config({}) - config["plugins"]["search"] = search_plugin - config["plugins"]["monorepo"] = monorepo_plugin - - # Markdown Extensions - if "markdown_extensions" not in config: - config["markdown_extensions"] = [] - - if "mdx_configs" not in config: - config["mdx_configs"] = {} - - config["markdown_extensions"].append("admonition") - config["markdown_extensions"].append("toc") - config["mdx_configs"]["toc"] = { - "permalink": True, - } - - config["markdown_extensions"].append("pymdownx.caret") - config["markdown_extensions"].append("pymdownx.critic") - config["markdown_extensions"].append("pymdownx.details") - config["markdown_extensions"].append("pymdownx.emoji") - config["mdx_configs"]["pymdownx.emoji"] = {"emoji_generator": to_svg} - config["markdown_extensions"].append("pymdownx.inlinehilite") - config["markdown_extensions"].append("pymdownx.magiclink") - config["markdown_extensions"].append("pymdownx.mark") - config["markdown_extensions"].append("pymdownx.smartsymbols") - config["markdown_extensions"].append("pymdownx.superfences") - config["mdx_configs"]["pymdownx.superfences"] = { - "legacy_tab_classes": True, - } - config["markdown_extensions"].append("pymdownx.highlight") - config["mdx_configs"]["pymdownx.highlight"] = { - "linenums": True, - } - config["markdown_extensions"].append("pymdownx.extra") - config["mdx_configs"]["pymdownx.betterem"] = { - "smart_enable": "all", - } - config["markdown_extensions"].append("pymdownx.tabbed") - config["markdown_extensions"].append("pymdownx.tasklist") - config["mdx_configs"]["pymdownx.tasklist"] = { - "custom_checkbox": True, - } - config["markdown_extensions"].append("pymdownx.tilde") - - config["markdown_extensions"].append("markdown_inline_graphviz") - config["markdown_extensions"].append("plantuml_markdown") - - # merge config supplied by user in the mkdocs.yml - for key in mdx_configs_override: - if key in config["mdx_configs"]: - default_config = config["mdx_configs"][key] - override_config = mdx_configs_override[key] - default_config.update(override_config) - - return config diff --git a/packages/techdocs-container/techdocs-core/src/test_core.py b/packages/techdocs-container/techdocs-core/src/test_core.py deleted file mode 100644 index 621570356c..0000000000 --- a/packages/techdocs-container/techdocs-core/src/test_core.py +++ /dev/null @@ -1,41 +0,0 @@ -import unittest -import mkdocs.config as config -import mkdocs.plugins as plugins -from .core import TechDocsCore - - -class DummyTechDocsCorePlugin(plugins.BasePlugin): - pass - - -class TestTechDocsCoreConfig(unittest.TestCase): - def setUp(self): - self.techdocscore = TechDocsCore() - self.plugin_collection = plugins.PluginCollection() - plugin = DummyTechDocsCorePlugin() - self.plugin_collection["techdocs-core"] = plugin - self.mkdocs_yaml_config = {"plugins": self.plugin_collection} - - def test_removes_techdocs_core_plugin_from_config(self): - final_config = self.techdocscore.on_config(self.mkdocs_yaml_config) - self.assertTrue("techdocs-core" not in final_config["plugins"]) - - def test_merge_default_config_and_user_config(self): - self.mkdocs_yaml_config["markdown_extension"] = [] - self.mkdocs_yaml_config["mdx_configs"] = {} - self.mkdocs_yaml_config["markdown_extension"].append(["toc"]) - self.mkdocs_yaml_config["mdx_configs"]["toc"] = {"toc_depth": 3} - final_config = self.techdocscore.on_config(self.mkdocs_yaml_config) - self.assertTrue("toc" in final_config["mdx_configs"]) - self.assertTrue("permalink" in final_config["mdx_configs"]["toc"]) - self.assertTrue("toc_depth" in final_config["mdx_configs"]["toc"]) - - def test_override_default_config_with_user_config(self): - self.mkdocs_yaml_config["markdown_extension"] = [] - self.mkdocs_yaml_config["mdx_configs"] = {} - self.mkdocs_yaml_config["markdown_extension"].append(["toc"]) - self.mkdocs_yaml_config["mdx_configs"]["toc"] = {"permalink": False} - final_config = self.techdocscore.on_config(self.mkdocs_yaml_config) - self.assertTrue("toc" in final_config["mdx_configs"]) - self.assertTrue("permalink" in final_config["mdx_configs"]["toc"]) - self.assertFalse(final_config["mdx_configs"]["toc"]["permalink"]) From 9d800c49ccfb7ed8044d609c193f64122d824e27 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 3 Nov 2020 11:47:35 +0100 Subject: [PATCH 2/4] TechDocs: Remove unnecessary GitHub workflow steps --- .github/workflows/techdocs-pypi.yml | 37 ----------------------------- .github/workflows/techdocs.yml | 11 --------- 2 files changed, 48 deletions(-) delete mode 100644 .github/workflows/techdocs-pypi.yml diff --git a/.github/workflows/techdocs-pypi.yml b/.github/workflows/techdocs-pypi.yml deleted file mode 100644 index 7680cb98b0..0000000000 --- a/.github/workflows/techdocs-pypi.yml +++ /dev/null @@ -1,37 +0,0 @@ -name: Master Build TechDocs PyPI Publish - -on: - push: - branches: [master] - paths: - - '.github/workflows/techdocs-pypi.yml' - - 'packages/techdocs-container/**' - -jobs: - build: - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: [ubuntu-latest] - python-version: [3.7] - - steps: - # Publish techdocs-core to PyPI - - uses: actions/checkout@v2 - - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@master - with: - python-version: 3.7 - - name: Build Python distribution - working-directory: ./packages/techdocs-container/techdocs-core - run: | - pip install wheel - rm -rf dist - python setup.py bdist_wheel sdist --formats gztar - - name: Publish a Python distribution to PyPI - uses: pypa/gh-action-pypi-publish@master - with: - user: __token__ - password: ${{ secrets.PYPI_API_KEY }} - packages_dir: ./packages/techdocs-container/techdocs-core/dist diff --git a/.github/workflows/techdocs.yml b/.github/workflows/techdocs.yml index 95b68c9376..9b5ea50217 100644 --- a/.github/workflows/techdocs.yml +++ b/.github/workflows/techdocs.yml @@ -31,14 +31,3 @@ jobs: with: path: packages/techdocs-container push: false - - # Lint Python code for techdocs-core package - - name: Prepare Python environment - run: | - python3 -m pip install --index-url https://pypi.org/simple/ setuptools - python3 -m pip install --upgrade pip - python3 -m pip install --index-url https://pypi.org/simple/ -r $TECHDOCS_CORE_PATH/requirements.txt - - - name: Lint techdocs-core package - run: | - python3 -m black --check $TECHDOCS_CORE_PATH/src From 878eb6095895797c3207be79d466b5a19a3c58c1 Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 3 Nov 2020 11:49:01 +0100 Subject: [PATCH 3/4] TechDocs: Update repo URL in documentation: --- docs/features/techdocs/FAQ.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/features/techdocs/FAQ.md b/docs/features/techdocs/FAQ.md index 080346b9d0..257d6e6f7a 100644 --- a/docs/features/techdocs/FAQ.md +++ b/docs/features/techdocs/FAQ.md @@ -23,8 +23,7 @@ is using the MkDocs #### What is the mkdocs-techdocs-core plugin? -The -[mkdocs-techdocs-core](https://github.com/backstage/backstage/blob/master/packages/techdocs-container/techdocs-core/README.md) +The [mkdocs-techdocs-core](https://github.com/backstage/mkdocs-techdocs-core) package is a MkDocs Plugin that works like a wrapper around multiple MkDocs plugins (e.g. [MkDocs Monorepo Plugin](https://github.com/spotify/mkdocs-monorepo-plugin)) as From 0672a3ecb16e9479ab1dcd41e64692595e8dd88c Mon Sep 17 00:00:00 2001 From: Himanshu Mishra Date: Tue, 3 Nov 2020 12:36:42 +0100 Subject: [PATCH 4/4] TechDocs: Remove unnecessary CODEOWNERS config --- .github/CODEOWNERS | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7cce08798a..cf28c55cb3 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -13,5 +13,4 @@ /packages/techdocs-cli @backstage/techdocs-core /packages/techdocs-container @backstage/techdocs-core /.github/workflows/techdocs.yml @backstage/techdocs-core -/.github/workflows/techdocs-pypi.yml @backstage/techdocs-core /.changeset/cost-insights-* @backstage/silver-lining