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

Provide a way of presenting the per-parameter documentation included in the config in a visually 'nice' way

    XMLWordPrintable

    Details

      Description

      The currrent Doxygen documentation generates documentation for options in the config class of tasks. However, the quality of the documentation generated leaves a lot to be desired: Doxygen merely embeds a block of code that just happens to include the help string but also includes a lot of unnecessary code. This makes the config parameters hard to find, hard to parse (by humans) and makes them very inconvenient to use when documenting source code. Provide some method for presenting the config options in a visually pleasing manner.

        Attachments

          Issue Links

          mentioned in

          Page Loading...

            Activity

            Ascending order - Click to sort in descending order
            Hide
            Permalink
            swinbank John Swinbank added a comment - - edited

            Actually, I think the description above slightly undersells the issue.

            As far as I can see from looking e.g. here, Doxygen doesn't even really copy the help strings – it just embeds blocks of code which include the (unformatted) help strings as well as a bunch of other boilerplate. That's not just ugly ("visually pleasing" is nice, but isn't top priority), but it's hard to find, hard to include in the task documentation, etc.

            Show
            swinbank John Swinbank added a comment - - edited Actually, I think the description above slightly undersells the issue. As far as I can see from looking e.g. here , Doxygen doesn't even really copy the help strings – it just embeds blocks of code which include the (unformatted) help strings as well as a bunch of other boilerplate. That's not just ugly ("visually pleasing" is nice, but isn't top priority), but it's hard to find, hard to include in the task documentation, etc.
            Hide
            Permalink
            jsick Jonathan Sick added a comment -

            I completely agree that the current Doxygen setup is completely unacceptable, and we’re actively replacing Doxygen as our user-facing documentation system.

            Steps are

            1. Production deployment of LSST the Docs, our continuous delivery platform for Sphinx documentation for EUPS products. Follow DM-5404. This will happen early in the X2016 cycle.
            2. Roll out Sphinx documentation projects into each Stack package and generate API references through Numpydoc for Python codebases and Doxygen->Breathe->Sphinx for C++ codebases. This will solve the problems you’re mentioning.

            I don’t know exactly when Step 2 will happen since documentation systems are not a SQuaRE priority for X2016. Likely we’ll see the migration happen in full by July/August 2016.

            Show
            jsick Jonathan Sick added a comment - I completely agree that the current Doxygen setup is completely unacceptable, and we’re actively replacing Doxygen as our user-facing documentation system. Steps are 1. Production deployment of LSST the Docs, our continuous delivery platform for Sphinx documentation for EUPS products. Follow DM-5404 . This will happen early in the X2016 cycle. 2. Roll out Sphinx documentation projects into each Stack package and generate API references through Numpydoc for Python codebases and Doxygen->Breathe->Sphinx for C++ codebases. This will solve the problems you’re mentioning. I don’t know exactly when Step 2 will happen since documentation systems are not a SQuaRE priority for X2016. Likely we’ll see the migration happen in full by July/August 2016.
            Hide
            Permalink
            swinbank John Swinbank added a comment -

            I think this is obsolete, given that config documentation is now well supported through Sphinx.

            Show
            swinbank John Swinbank added a comment - I think this is obsolete, given that config documentation is now well supported through Sphinx.

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              vpk24 Vishal Kasliwal [X] (Inactive)
              Watchers:
              John Swinbank, Jonathan Sick, Vishal Kasliwal [X] (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.