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

Implement C++ reference documentation for pipelines.lsst.io using "Doxylink"

    XMLWordPrintable

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: documenteer
    • Labels:
      None

      Description

      Investigate using Doxylink to link to an HTML Doxygen build of the C++ API reference compiled alongside the main Sphinx site.

      This work would build upon DM-22698, which gave Documenteer the ability to run a Sphinx build. In this scenario, Documenteer would build the Sphinx site, and then embed it as a sub-site (subdirectory) of the Sphinx-generated documentation. Doxylink would let us link between from reStructuredText to Doxygen using a custom role. For example:

      :lsstcc:`lsst::afw::table::Schema`
      

      Of course, links from Doxygen to the Sphinx site would not be straightforward (in princple, they could be added manually, though that would be prone to fail if URLs change).

        Attachments

          Issue Links

            Activity

            Hide
            jsick Jonathan Sick added a comment -

            The prototype is working well, though Doxylink is failing to parse about 400 API signatures from the Doxygen tag file. I've listed these APIs at https://gist.github.com/jonathansick/8683a0b3a5f932b1063e2c71bbaa9de5

            Krzysztof Findeisen, if you could take a look at the APIs in the above link, do you see some common patterns? Are they using C+11 or 14 features? I'm not a C+ dev, but if I could have your assessment I could get the Doxylink developers to adjust their parsers to work with our C++ API signatures. Thanks!

            Show
            jsick Jonathan Sick added a comment - The prototype is working well, though Doxylink is failing to parse about 400 API signatures from the Doxygen tag file. I've listed these APIs at https://gist.github.com/jonathansick/8683a0b3a5f932b1063e2c71bbaa9de5 Krzysztof Findeisen , if you could take a look at the APIs in the above link, do you see some common patterns? Are they using C+ 11 or 14 features? I'm not a C + dev, but if I could have your assessment I could get the Doxylink developers to adjust their parsers to work with our C++ API signatures. Thanks!
            Hide
            krzys Krzysztof Findeisen added a comment - - edited

            It looks like all the methods in your list either:

            • have the noexcept keyword,
            • are operator(), or
            • use macros (especially PTR, which we should have gotten rid of by now).

            I'm not sure yet about the converse.

            I noticed that some of the entries are listed by filename, others with a namespace, still others without a namespace. What's the significance of that?

            Show
            krzys Krzysztof Findeisen added a comment - - edited It looks like all the methods in your list either: have the noexcept keyword, are operator() , or use macros (especially PTR , which we should have gotten rid of by now). I'm not sure yet about the converse. I noticed that some of the entries are listed by filename, others with a namespace, still others without a namespace. What's the significance of that?
            Hide
            krzys Krzysztof Findeisen added a comment -

            Are lsst::afw::detection::IdSpanCompar or lsst::meas::base::BaseTransform in your documentation? Their operator() don't seem to have raised any errors.

            Show
            krzys Krzysztof Findeisen added a comment - Are lsst::afw::detection::IdSpanCompar or lsst::meas::base::BaseTransform in your documentation? Their operator() don't seem to have raised any errors.
            Hide
            jsick Jonathan Sick added a comment -

            Progress update:

            • The stack-docs build command now builds an HTML site, along with a tag file. The HTML site gets copied into the /cpp-api/ directory of the Sphinx build for pipelines.lsst.io.
            • Configure the sphinxcontrib.doxylink extension to add an lsstcc role to enable links from reStructuredText content into the Doxygen-build C++ API reference.
            • Added a tool, stack-docs listcc to help authors find APIs that can be linked with the lsstcc role.
            • Added documentation about C++ linking and updated the documentation about the pipelines.lsst.io build.
            Show
            jsick Jonathan Sick added a comment - Progress update: The stack-docs build command now builds an HTML site, along with a tag file. The HTML site gets copied into the /cpp-api/ directory of the Sphinx build for pipelines.lsst.io. Configure the sphinxcontrib.doxylink extension to add an lsstcc role to enable links from reStructuredText content into the Doxygen-build C++ API reference. Added a tool, stack-docs listcc to help authors find APIs that can be linked with the lsstcc role. Added documentation about C++ linking and updated the documentation about the pipelines.lsst.io build.
            Hide
            krzys Krzysztof Findeisen added a comment -

            Does the lsstcc role replace the previously documented cpp role?

            Show
            krzys Krzysztof Findeisen added a comment - Does the lsstcc role replace the previously documented cpp role ?
            Hide
            jsick Jonathan Sick added a comment - - edited

            It does; doxylink doesn't use the cpp domain's roles because there aren't any cpp directives to link to. Instead, it creates plain relative hyperlinks to the Doxygen subsite.

            Show
            jsick Jonathan Sick added a comment - - edited It does; doxylink doesn't use the cpp domain's roles because there aren't any cpp directives to link to. Instead, it creates plain relative hyperlinks to the Doxygen subsite.
            Hide
            jsick Jonathan Sick added a comment -

            We're going to go ahead and merge this into the documenteer, which will eventually be released in documenteer 0.6.

            Show
            jsick Jonathan Sick added a comment - We're going to go ahead and merge this into the documenteer, which will eventually 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:

                  CI Builds

                  No builds found.