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

Investigate inconsistent Doxygen building

    XMLWordPrintable

    Details

    • Story Points:
      4
    • Epic Link:
    • Sprint:
      AP S18-2, AP S18-3
    • Team:
      Alert Production

      Description

      Stack documentation built with the buildbot script does not look the same as stack documentation built with single-package calls to scons doc, even when run in the same environment on the same machine. Specifically:

      • Single-package docs use Javascript search, while the buildbot docs defer to a PHP script. This affects usability because the latter gives much poorer results (more false positives, and closest match not at the top of the list).
      • Single-package docs show only public or protected class members, while buildbot docs also display private members.

      Most changes to base.inc are reflected in the buildbot docs, so it appears that some settings are being overridden rather than the Stack's Doxygen configuration being ignored completely.

      This ticket is primarily for understanding where the different behavior comes from, rather than changing the settings to be more consistent. (In particular, I assume the search functionality will be irrelevant once we migrate to Sphinx.)

        Attachments

          Issue Links

          relates to

          RFC - An issue whose primary purpose is to advertise an intent and allow stakeholders to comment. RFC-451 Do not document private class members in published Stack API documentation

          • Implemented

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-13123 Doxygen search broken

          • Done

            Activity

            Ascending order - Click to sort in descending order
            Hide
            Permalink
            krzys Krzysztof Findeisen added a comment - - edited

            I've finished looking into why the buildbot documentation does not look like the scons doc docs.

            The search implementation is a deliberate override in lsstDoxygen/bin/makeDocs, which forces the shared documentation build to use SERVER_BASED_SEARCH = YES. This setting was provided in the initial commit of lsstDoxygen, so I don't know what the rationale was behind the decision. I have locally tested the default Javascript-based search, and it does not have any performance problems at the scale of the full-Stack docs (and, as expected, the class or method being looked for actually appears first in the results). I will propose on DM-13123 that we switch to client-based search, since that would also solve the issue of the server not running PHP.

            The origin of the private members is stranger. makeDocs imports documentation overrides from Stack packages, adopting the first override encountered in iteration order. For EXTRACT_PRIVATE this happens to be ip_diffim, which is the only package in the entire Stack to set it to YES (six other packages set it to NO, the others leave it at default). I found the commit that made the change, but no justification was provided and I couldn't find the corresponding Jira issue. I will see if the current ip_diffim people have any objection to changing it back, but EXTRACT_PRIVATE = NO could also be added as an override in makeDocs.

            Show
            krzys Krzysztof Findeisen added a comment - - edited I've finished looking into why the buildbot documentation does not look like the scons doc docs. The search implementation is a deliberate override in lsstDoxygen/bin/makeDocs , which forces the shared documentation build to use SERVER_BASED_SEARCH = YES . This setting was provided in the initial commit of lsstDoxygen , so I don't know what the rationale was behind the decision. I have locally tested the default Javascript-based search, and it does not have any performance problems at the scale of the full-Stack docs (and, as expected, the class or method being looked for actually appears first in the results). I will propose on DM-13123 that we switch to client-based search, since that would also solve the issue of the server not running PHP. The origin of the private members is stranger. makeDocs imports documentation overrides from Stack packages, adopting the first override encountered in iteration order. For EXTRACT_PRIVATE this happens to be ip_diffim , which is the only package in the entire Stack to set it to YES (six other packages set it to NO , the others leave it at default). I found the commit that made the change, but no justification was provided and I couldn't find the corresponding Jira issue. I will see if the current ip_diffim people have any objection to changing it back, but EXTRACT_PRIVATE = NO could also be added as an override in makeDocs .
            Hide
            Permalink
            tjenness Tim Jenness added a comment -

            It was DM-912 that added the EXTRACT_PRIVATE line to ip_diffim. It does look to be a deliberate change for the documentation.

            Show
            tjenness Tim Jenness added a comment - It was DM-912 that added the EXTRACT_PRIVATE line to ip_diffim . It does look to be a deliberate change for the documentation.
            Hide
            Permalink
            krzys Krzysztof Findeisen added a comment -

            Thanks, that helps.

            Show
            krzys Krzysztof Findeisen added a comment - Thanks, that helps.

              People

              Assignee:
              krzys Krzysztof Findeisen
              Reporter:
              krzys Krzysztof Findeisen
              Watchers:
              Jonathan Sick, Joshua Hoblitt, Krzysztof Findeisen, Tim Jenness
              Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.