Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-22461

Create Sphinx "autocppapi" extension in Documenteer

    Details

      Description

      The goal of this extension is to render C++ documentation (generated by Doxygen and Breathe) equivalently to how we already render Python API documentation in pipelines.lsst.io using the automodapi directive.

      automodapi creates a contents table of all the functions and classes available in a Python module namespace. It also generates rst pages (in an /py-api/ directory) with placeholders for standard Sphinx autoapi directives for individual Python functions and classes.

      What this does is ensure that each function and class has its own page.

      This is different from Breath's default behaviour with its doxygennamespace directive, which inserts all documentation for a given namespace into one page.

      This extension will be implemented in https://github.com/lsst-sqre/documenteer

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            Change log entry:

            There is a new directive, ``autocppapi``, part of the ``documenteer.ext.autocppapi`` extension, that helps you list and link to C++ APIs in a namespace. It's intended to be used equivalently to the ``automodapi`` extension.

            This solution integrates with Doxylink (DM-23094) and works well with the built-in Doxygen subsite approach we're taking in documenteer 0.6. There are opportunities to improve the presentation, like scraping the class summary from the Doxygen XML output and showing it in the listing, but this is a functional minimum-viable product.

            Will be released in documenteer 0.6.

            Show
            jsick Jonathan Sick added a comment - Change log entry: There is a new directive, ``autocppapi``, part of the ``documenteer.ext.autocppapi`` extension, that helps you list and link to C++ APIs in a namespace. It's intended to be used equivalently to the ``automodapi`` extension. This solution integrates with Doxylink ( DM-23094 ) and works well with the built-in Doxygen subsite approach we're taking in documenteer 0.6. There are opportunities to improve the presentation, like scraping the class summary from the Doxygen XML output and showing it in the listing, but this is a functional minimum-viable product. Will be released in documenteer 0.6.

              People

              • Assignee:
                jsick Jonathan Sick
                Reporter:
                jsick Jonathan Sick
                Watchers:
                Jonathan Sick, Krzysztof Findeisen
              • Votes:
                0 Vote for this issue
                Watchers:
                2 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: