opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-05-21 09:05:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Use a new markdown converter for sphinx

Browse Source 
Recommonmark has many issues and is deprecated. The recommended
alternative is MyST-Parser. [1]

The myst parser looks great, it also correctly parses tables and adds the
correct links.

To test locallay run:
```
cd docs
rm -rf build/
\# install build deps
sudo dnf install python3-sphinx && pip install myst-parser
make html
python -m http.server 8000 --directory build/html
\# Now check in your browser if it looks good to you
```

[1] https://github.com/readthedocs/recommonmark/issues/221

Signed-off-by: Paul Holzinger <pholzing@redhat.com>
This commit is contained in:
Paul Holzinger
2021-09-16 18:57:36 +02:00
parent 9119a578e7
commit 7ca666f474
2 changed files with 8 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/requirements.txt
View File

@ -1,6 +1,4 @@
# requirements file for readthedocs pip installs # requirements file for readthedocs pip installs
# use md instead of rst # use md instead of rst
recommonmark myst_parser
# needed for markdown table support
sphinx-markdown-tables

24
docs/source/conf.py
View File

@ -15,7 +15,6 @@
# sys.path.insert(0, os.path.abspath('.')) # sys.path.insert(0, os.path.abspath('.'))
import re import re
from recommonmark.transform import AutoStructify
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
@ -29,7 +28,7 @@ author = "team"
# Add any Sphinx extension module names here, as strings. They can be # Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones. # ones.
extensions = ["sphinx_markdown_tables", "recommonmark"] extensions = ["myst_parser"]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"] templates_path = ["_templates"]
@ -63,27 +62,18 @@ html_css_files = [
# -- Extension configuration ------------------------------------------------- # -- Extension configuration -------------------------------------------------
# IMPORTANT: explicitly unset the extensions, by default dollarmath is enabled.
# We use the dollar sign as text and do not want it to be interpreted as math expression.
myst_enable_extensions = []
def convert_markdown_title(app, docname, source): def convert_markdown_title(app, docname, source):
# Process markdown files only # Process markdown files only
docpath = app.env.doc2path(docname) docpath = app.env.doc2path(docname)
if docpath.endswith(".md"): if docpath.endswith(".md"):
# Convert pandoc title line into eval_rst block for recommonmark # Convert pandoc title line into eval_rst block for myst_parser
source[0] = re.sub(r"^% (.*)", r"```eval_rst\n.. title:: \g<1>\n```", source[0]) source[0] = re.sub(r"^% (.*)", r"```{title} \g<1>\n```", source[0])
def setup(app): def setup(app):
app.connect("source-read", convert_markdown_title) app.connect("source-read", convert_markdown_title)
app.add_config_value(
"recommonmark_config",
{
"enable_eval_rst": True,
"enable_auto_doc_ref": False,
"enable_auto_toc_tree": False,
"enable_math": False,
"enable_inline_math": False,
},
True,
)
app.add_transform(AutoStructify)