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

Create Sphinx "autocppapi" extension in Documenteer

    XMLWordPrintable

    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

          relates to

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-22499 Trial generating C++ documentation for pipelines.lsst.io using Breathe's breathe-apidoc tool

          • Done

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-22500 Trial generating C++ documentation for pipelines.lsst.io using "exhale"

          • Done

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-26841 Update documenteer's doxygen configuration to encompass base configs

          • Done

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-19574 Add doxygen C++ documentation to module homepages

          • To Do

            Activity

            Hide
            Permalink
            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:

                  Jenkins

                  No builds found.