summaryrefslogtreecommitdiff
path: root/docs/source
diff options
context:
space:
mode:
authorPaul Holzinger <pholzing@redhat.com>2021-09-16 18:57:36 +0200
committerMatthew Heon <matthew.heon@pm.me>2021-09-22 17:11:40 -0400
commit8ee18bde152da71f1b7ba9d7575324321be630d6 (patch)
tree30e609a0167631176b9dc032c3751e697b9077b9 /docs/source
parent9dd75d311601ec810dad6339faad1eec5cf28fe5 (diff)
downloadpodman-8ee18bde152da71f1b7ba9d7575324321be630d6.tar.gz
podman-8ee18bde152da71f1b7ba9d7575324321be630d6.tar.bz2
podman-8ee18bde152da71f1b7ba9d7575324321be630d6.zip
Use a new markdown converter for sphinx
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>
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/conf.py24
1 files changed, 7 insertions, 17 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8210022f2..7684dd3f7 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -15,7 +15,6 @@
# sys.path.insert(0, os.path.abspath('.'))
import re
-from recommonmark.transform import AutoStructify
# -- Project information -----------------------------------------------------
@@ -29,7 +28,7 @@ author = "team"
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
-extensions = ["sphinx_markdown_tables", "recommonmark"]
+extensions = ["myst_parser"]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
@@ -63,27 +62,18 @@ html_css_files = [
# -- 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):
# Process markdown files only
docpath = app.env.doc2path(docname)
if docpath.endswith(".md"):
- # Convert pandoc title line into eval_rst block for recommonmark
- source[0] = re.sub(r"^% (.*)", r"```eval_rst\n.. title:: \g<1>\n```", source[0])
+ # Convert pandoc title line into eval_rst block for myst_parser
+ source[0] = re.sub(r"^% (.*)", r"```{title} \g<1>\n```", source[0])
def setup(app):
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)