From 7ca666f47492f60185efcbcacfddb2c8e7dc661a Mon Sep 17 00:00:00 2001 From: Paul Holzinger Date: Thu, 16 Sep 2021 18:57:36 +0200 Subject: 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 --- docs/requirements.txt | 4 +--- docs/source/conf.py | 24 +++++++----------------- 2 files changed, 8 insertions(+), 20 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 84e7ec6a5..3ba6d658f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,4 @@ # requirements file for readthedocs pip installs # use md instead of rst -recommonmark -# needed for markdown table support -sphinx-markdown-tables +myst_parser 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) -- cgit v1.2.3-54-g00ecf