From fd1e0927178ac6e2bb7b7dded5609d1c4348b7a3 Mon Sep 17 00:00:00 2001 From: Abrar Rahman Protyasha Date: Thu, 29 Jul 2021 17:21:19 -0400 Subject: [PATCH 1/2] Reorganized `SphinxBuilder` for markdown parsing * Removed a stray TODO comment from an experimental idea for #22. * Moved the `lexerMapping` changes to `exhale` arguments into the conditional `support_markdown` block, so that the appropriate Pygments lexer is only registered if support for markdown was enabled. * Added longer description of the `support_markdown` option. Signed-off-by: Abrar Rahman Protyasha --- .../verbs/build/builders/sphinx_builder.py | 28 +++++++++++-------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/rosdoc2/verbs/build/builders/sphinx_builder.py b/rosdoc2/verbs/build/builders/sphinx_builder.py index 2153472..f289c44 100644 --- a/rosdoc2/verbs/build/builders/sphinx_builder.py +++ b/rosdoc2/verbs/build/builders/sphinx_builder.py @@ -87,14 +87,6 @@ def ensure_global(name, default): # TIP: if using the sphinx-bootstrap-theme, you need # "treeViewIsBootstrap": True, "exhaleExecutesDoxygen": False, - # Maps markdown files to the "md" lexer, and not the "markdown" lexer - # Pygments registers "md" as a valid markdown lexer, and not "markdown" - "lexerMapping": {{r".*\.(md|markdown)$": "md",}}, - # This mapping will work when `exhale` supports `:doxygenpage:` directives - # Check https://github.com/svenevs/exhale/issues/111 - # TODO(aprotyas): Uncomment the mapping below once the above issue is resolved. - # "customSpecificationsMapping": utils.makeCustomSpecificationsMapping( - # lambda kind: [":project:", ":path:", ":content-only:"] if kind == "page" else []), }}) if rosdoc2_settings.get('override_theme', True): @@ -116,9 +108,19 @@ def ensure_global(name, default): print(f"[rosdoc2] adding markdown parser", file=sys.stderr) # The `myst_parser` is used specifically if there are markdown files # in the sphinx project - # TODO(aprotyas): Migrate files under the `include` tag in the project's Doxygen - # configuration into the Sphinx project tree used to run the Sphinx builder in. extensions.append('myst_parser') + # If markdown support is enabled, the appropriate Pygments lexer must + # be registered for `.md`/`.markdown` file suffixes + exhale_args.update({{ + # Maps markdown files to the "md" lexer, and not the "markdown" lexer + # Pygments registers "md" as a valid markdown lexer, and not "markdown" + "lexerMapping": {{r".*\.(md|markdown)$": "md",}}, + # This mapping will work when `exhale` supports `:doxygenpage:` directives + # Check https://github.com/svenevs/exhale/issues/111 + # TODO(aprotyas): Uncomment the mapping below once the above issue is resolved. + # "customSpecificationsMapping": utils.makeCustomSpecificationsMapping( + # lambda kind: [":project:", ":path:", ":content-only:"] if kind == "page" else []), + }}) """ default_conf_py_template = """\ @@ -237,7 +239,11 @@ def ensure_global(name, default): ## Sphinx conf.py file. # 'automatically_extend_intersphinx_mapping': True, - ## Support markdown + ## This setting, if True, will add the `myst_parser` as an extension to + ## `sphinx`, hence allowing support for markdown rendering. This will also + ## register the `md` Pygments lexer with `.md`/`.markdown` file suffixes, so + ## that `exhale` can perform appropriate markdown syntax highlighting for + ## program listing rst files. # 'support_markdown': True, }} """ From 6281b4951bbfd3c63437b663fe1c029f2c3b5407 Mon Sep 17 00:00:00 2001 From: Abrar Rahman Protyasha Date: Thu, 5 Aug 2021 12:44:28 -0400 Subject: [PATCH 2/2] Check `exhale` support before registering md lexer The `exhale_args` mapping should only be updated with the appropriate Pygments markdown lexer if both markdown support and exhale support are requested. As such, an additional check for `enable_exhale` is added into the markdown support configuration block. An alternative would be to invoke `ensure_global` on `exhale_args`, but that may create a needless copy of `exhale_args` incase `enable_exhale` is false. Signed-off-by: Abrar Rahman Protyasha --- .../verbs/build/builders/sphinx_builder.py | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/rosdoc2/verbs/build/builders/sphinx_builder.py b/rosdoc2/verbs/build/builders/sphinx_builder.py index f289c44..234d3f1 100644 --- a/rosdoc2/verbs/build/builders/sphinx_builder.py +++ b/rosdoc2/verbs/build/builders/sphinx_builder.py @@ -109,18 +109,20 @@ def ensure_global(name, default): # The `myst_parser` is used specifically if there are markdown files # in the sphinx project extensions.append('myst_parser') + # If markdown support is enabled, the appropriate Pygments lexer must # be registered for `.md`/`.markdown` file suffixes - exhale_args.update({{ - # Maps markdown files to the "md" lexer, and not the "markdown" lexer - # Pygments registers "md" as a valid markdown lexer, and not "markdown" - "lexerMapping": {{r".*\.(md|markdown)$": "md",}}, - # This mapping will work when `exhale` supports `:doxygenpage:` directives - # Check https://github.com/svenevs/exhale/issues/111 - # TODO(aprotyas): Uncomment the mapping below once the above issue is resolved. - # "customSpecificationsMapping": utils.makeCustomSpecificationsMapping( - # lambda kind: [":project:", ":path:", ":content-only:"] if kind == "page" else []), - }}) + if rosdoc2_settings.get('enable_exhale'): + exhale_args.update({{ + # Maps markdown files to the "md" lexer, and not the "markdown" lexer + # Pygments registers "md" as a valid markdown lexer, and not "markdown" + "lexerMapping": {{r".*\.(md|markdown)$": "md",}}, + # This mapping will work when `exhale` supports `:doxygenpage:` directives + # Check https://github.com/svenevs/exhale/issues/111 + # TODO(aprotyas): Uncomment the mapping below once the above issue is resolved. + # "customSpecificationsMapping": utils.makeCustomSpecificationsMapping( + # lambda kind: [":project:", ":path:", ":content-only:"] if kind == "page" else []), + }}) """ default_conf_py_template = """\