Add breate_doxygen_aliases config value

The configuration option enables users to add custom commands to doxygen
when using `autodoxygenindex` and `autodoxygenfile`.

There is no obvious way to add an automatic test for this without
considerable effort. It has been tested manually.

README.rst

@@ -174,6 +174,8 @@ Inspired by `Keepachangelog.com <http://keepachangelog.com/>`__.
 - Unreleased - Breathe v4.31.0
 
   - Collapse multiple retvals into a single bullet list. #697
+  - Added ``breathe_doxygen_aliases`` config variable which allows for adding
+      more aliases to the doxygen file used for the auto-directives.
 
 - 2021-05-06 - Breathe v4.30.0
 

breathe/directives.py

@@ -589,6 +589,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')
@@ -614,6 +615,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

@@ -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,13 +65,13 @@ 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
@@ -82,7 +82,8 @@ def process(self, auto_project_info, files, doxygen_options):
             project_name=name,
             output_dir=name,
             input=" ".join(full_paths),
-            extra='\n'.join("%s=%s" % pair for pair in doxygen_options.items())
+            extra='\n'.join("%s=%s" % pair for pair in doxygen_options.items()) + "\n"
+                  + '\n'.join(f'ALIASES += {name}="{value}"' for name, value in doxygen_aliases.items())
             )
 
         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.