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 <[email protected]>

Author: Abrar Rahman Protyasha

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',
 }}
 """