Merge pull request #729 from BenWhetton/add_doxygen_aliases

Add breate_doxygen_aliases config value

CHANGELOG.rst

@@ -3,6 +3,10 @@ Change Log
 
 Inspired by `Keepachangelog.com <http://keepachangelog.com/>`__.
 
+- Unreleased
+
+  - Added ``breathe_doxygen_aliases`` config variable. `#729 <https://github.com/michaeljones/breathe/pull/729>`__
+
 - 2021-09-14 - **Breathe v4.31.0**
 
   - Collapse multiple retvals into a single bullet list. `#697 <https://github.com/michaeljones/breathe/pull/697>`__

breathe/directives/setup.py

@@ -103,6 +103,7 @@ def setup(app: Sphinx) -> None:
     app.add_config_value("breathe_show_enumvalue_initializer", False, 'env')
     app.add_config_value("breathe_implementation_filename_extensions", ['.c', '.cc', '.cpp'], True)
     app.add_config_value("breathe_doxygen_config_options", {}, True)
+    app.add_config_value("breathe_doxygen_aliases", {}, True)
     app.add_config_value("breathe_use_project_refids", False, "env")
     app.add_config_value("breathe_order_parameters_first", False, 'env')
     app.add_config_value("breathe_separate_member_pages", False, 'env')
@@ -128,6 +129,7 @@ def write_file(directory, filename, content):
     def doxygen_hook(app):
         doxygen_handle.generate_xml(
             app.config.breathe_projects_source,
-            app.config.breathe_doxygen_config_options
+            app.config.breathe_doxygen_config_options,
+            app.config.breathe_doxygen_aliases
         )
     app.connect("builder-inited", doxygen_hook)

breathe/process.py

@@ -24,9 +24,9 @@
 JAVADOC_AUTOBRIEF = NO
 GENERATE_HTML = NO
 GENERATE_XML = YES
-ALIASES = "rst=\verbatim embed:rst"
-ALIASES += "endrst=\endverbatim"
-ALIASES += "inlinerst=\verbatim embed:rst:inline"
+ALIASES = rst="\verbatim embed:rst"
+ALIASES += endrst="\endverbatim"
+ALIASES += inlinerst="\verbatim embed:rst:inline"
 {extra}
 """.strip()
 
@@ -46,7 +46,7 @@ def __init__(self, run_process, write_file, project_info_factory: ProjectInfoFac
         self.write_file = write_file
         self.project_info_factory = project_info_factory
 
-    def generate_xml(self, projects_source, doxygen_options):
+    def generate_xml(self, projects_source, doxygen_options, doxygen_aliases):
 
         project_files = {}
 
@@ -65,24 +65,32 @@ def generate_xml(self, projects_source, doxygen_options):
         # a directory in the Sphinx build area
         for project_name, data in project_files.items():
 
-            project_path = self.process(data.auto_project_info, data.files, doxygen_options)
+            project_path = self.process(
+                data.auto_project_info,
+                data.files,
+                doxygen_options,
+                doxygen_aliases)
 
             project_info = data.auto_project_info.create_project_info(project_path)
 
             self.project_info_factory.store_project_info_for_auto(project_name, project_info)
 
-    def process(self, auto_project_info, files, doxygen_options):
+    def process(self, auto_project_info, files, doxygen_options, doxygen_aliases):
 
         name = auto_project_info.name()
         cfgfile = "%s.cfg" % name
 
         full_paths = map(lambda x: auto_project_info.abs_path_to_source_file(x), files)
 
+        options = "\n".join("%s=%s" % pair for pair in doxygen_options.items())
+        aliases = '\n'.join(
+            f'ALIASES += {name}="{value}"' for name, value in doxygen_aliases.items())
+
         cfg = AUTOCFG_TEMPLATE.format(
             project_name=name,
             output_dir=name,
             input=" ".join(full_paths),
-            extra='\n'.join("%s=%s" % pair for pair in doxygen_options.items())
+            extra=f"{options}\n{aliases}"
             )
 
         build_dir = os.path.join(

documentation/source/directives.rst

@@ -251,7 +251,9 @@ option associates the directive with a particular project in the
 ``breathe_projects_source`` dictionary. All the files references by the entry in
 the ``breathe_projects_source`` will be included in the output. In addition, any
 options specified in ``breathe_doxygen_config_options`` will be added to the
-generated Doxygen config file.
+generated Doxygen config file and any custom aliases specified in
+``breathe_doxygen_config_aliases`` will be added to the `doxygen aliases
+<https://www.doxygen.nl/manual/custcmd.html>`_.
 
 Thank you to `Scopatz <https://github.com/scopatz>`_ for the idea and initial
 implementation.
@@ -548,6 +550,23 @@ Config Values
    would place ``EXCLUDE_SYMBOLS=abc123`` in the config file. The default value is
    the empty dictionary.
 
+.. confval:: breathe_doxygen_aliases
+
+    A dictionnary in which the keys and values are the names and values of aliases
+    to be placed in the Doxygen config file generated by ``autodoxygenindex``.
+    For instance, this::
+
+      breathe_doxygen_aliases = {'rstref{1}': r'\verbatim embed:rst:inline :ref:`\1` \endverbatim'}
+
+    would place the line::
+
+      ALIASES += rstref{1}="\verbatim embed:rst:inline :ref:`\1` \endverbatim"
+
+    in the config file. The default value is an empty dictionary.
+    Note the use of a raw string to ensure that backslashes are interpreted as literal characters.
+    (This example alias enables linking to rst targets inline in doxygen comments using
+    ``\rstref{<target_name>}``)
+
 .. confval:: breathe_show_define_initializer
 
    A boolean flag which can be set to ``True`` to display the initializer of a define in the output.