Merge pull request #3216 from backstage/orkohunter/remove-techdocs-core-from-mono-repo
This commit is contained in:
Himanshu Mishra
@@ -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
|
||||
|
||||
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -1,2 +0,0 @@
|
||||
.tox
|
||||
*.egg-info
|
||||
@@ -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
|
||||
@@ -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
|
||||
@@ -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"]},
|
||||
)
|
||||
@@ -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
|
||||
@@ -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"])
|
||||
Reference in New Issue
Block a user