From f3ebfb614f45758cf289d5c159545591b5b28272 Mon Sep 17 00:00:00 2001 From: Abrar Rahman Protyasha Date: Thu, 29 Jul 2021 15:46:05 -0400 Subject: [PATCH 1/2] Add `rosdoc2` option to specify `primary_domain` This option should enable `sphinx` to land on reasonable defaults for code highlighting Pygments lexers, as well as other markup behaviors, depending on the domain of a package (defaults to `cpp`). Signed-off-by: Abrar Rahman Protyasha --- rosdoc2/verbs/build/builders/sphinx_builder.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/rosdoc2/verbs/build/builders/sphinx_builder.py b/rosdoc2/verbs/build/builders/sphinx_builder.py index 2153472..8e8d5e2 100644 --- a/rosdoc2/verbs/build/builders/sphinx_builder.py +++ b/rosdoc2/verbs/build/builders/sphinx_builder.py @@ -119,6 +119,16 @@ def ensure_global(name, default): # 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 no `primary_domain` option provided, defaults to 'cpp' +if rosdoc2_settings.get('primary_domain', 'cpp'): + print(f"[rosdoc2] setting primary domain to '{{rosdoc2_settings.get('primary_domain')}}'", + file=sys.stderr) + # Tell sphinx what the primary language being documented is. + primary_domain = rosdoc2_settings.get('primary_domain') + + # Tell sphinx what the pygments highlight language should be. + highlight_language = rosdoc2_settings.get('primary_domain') """ default_conf_py_template = """\ @@ -239,6 +249,13 @@ def ensure_global(name, default): ## Support markdown # 'support_markdown': True, + + ## This setting, if set, will attempt to set the `sphinx` options + ## `primary_domain` and `highlight_language` equal to this setting. These + ## options allow `sphinx` to choose reasonable defaults for source + ## code highlighting, among other things. + ## Possible values (without extensions): 'c', 'cpp', 'js', 'py' + # 'primary_domain': 'cpp', }} """ From ac4a5ea595ffd00a64d99c7a7eed4dc62bc773a9 Mon Sep 17 00:00:00 2001 From: Abrar Rahman Protyasha Date: Fri, 6 Aug 2021 00:18:31 -0400 Subject: [PATCH 2/2] Fix default `rosdoc2_settings.primary_domain` val Previously, this setting defaulted to `cpp`, which is not ideal because only be false if the user explicitly did `rosdoc2_settings = {'primary_domain': None}` or similar. This commit changes that default from `cpp` to `None`, which is more reasonable and closer to expected behavior from the user's POV. Signed-off-by: Abrar Rahman Protyasha --- rosdoc2/verbs/build/builders/sphinx_builder.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/rosdoc2/verbs/build/builders/sphinx_builder.py b/rosdoc2/verbs/build/builders/sphinx_builder.py index 8e8d5e2..f696961 100644 --- a/rosdoc2/verbs/build/builders/sphinx_builder.py +++ b/rosdoc2/verbs/build/builders/sphinx_builder.py @@ -120,8 +120,8 @@ def ensure_global(name, default): # configuration into the Sphinx project tree used to run the Sphinx builder in. extensions.append('myst_parser') -# if no `primary_domain` option provided, defaults to 'cpp' -if rosdoc2_settings.get('primary_domain', 'cpp'): +# if no `primary_domain` option provided, defaults to None +if rosdoc2_settings.get('primary_domain'): print(f"[rosdoc2] setting primary domain to '{{rosdoc2_settings.get('primary_domain')}}'", file=sys.stderr) # Tell sphinx what the primary language being documented is. @@ -254,8 +254,8 @@ def ensure_global(name, default): ## `primary_domain` and `highlight_language` equal to this setting. These ## options allow `sphinx` to choose reasonable defaults for source ## code highlighting, among other things. - ## Possible values (without extensions): 'c', 'cpp', 'js', 'py' - # 'primary_domain': 'cpp', + ## Possible values (without extensions): 'c', 'cpp', 'js', 'py', None + # 'primary_domain': None, }} """