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

Develop Sphinx configuration for Pipelines Documentation, including MVP HTML/CSS Template

    XMLWordPrintable

    Details

      Description

      This ticket will kick-off a pilot implementation of pipelines documentation in Sphinx. Specific goals are

      1. Develop template for sphinx-ready doc/ directories in packages (based on SQR-006)
      2. Setup a MVP sphinx template that works well with numpydoc and astropy automodsumm. Simply porting astropy’s sphinx template would be pragmatic.
      3. documenteer-driven configuration for sphinx.

      These will be MVPs, and iterated upon in later tickets that implement sphinx API docs for stack packages.

        Attachments

          Issue Links

          has to be done before

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-7095 Pilot Sphinx/Breath/Doxygen-generated API docs for daf_base

          • Done
          relates to

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-7096 Draft Pipelines Documentation Implementation Plan technote

          • Done

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-7885 Add “Powered by Fastly” to technotes themes

          • Invalid

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-7042 validate_base API refinement

          • Done

            Activity

            Ascending order - Click to sort in descending order
            Hide
            Permalink
            jsick Jonathan Sick added a comment -

            Just discovered some details on documenting class attributes with the astropy-helpers/documenteer Sphinx setup.

            1. Don’t use the Attributes numpydoc section; those entries will be separate from the entries for properties.
            2. Use the “””Docstring””” syntax under the class attribute to document it. It does matter whether this is done in the class scope or inside an _init_.
            3. The variable must be declared in the class scope first for autodoc to see it. You can’t just declare it in _init_.
            Show
            jsick Jonathan Sick added a comment - Just discovered some details on documenting class attributes with the astropy-helpers / documenteer Sphinx setup. Don’t use the Attributes numpydoc section; those entries will be separate from the entries for properties. Use the “””Docstring””” syntax under the class attribute to document it. It does matter whether this is done in the class scope or inside an _ init _ . The variable must be declared in the class scope first for autodoc to see it. You can’t just declare it in _ init _ .
            Hide
            Permalink
            jsick Jonathan Sick added a comment - - edited

            documenteer released to PyPI as v0.1.10

            lsst-sphinx-bootstrap-theme was released to PyPI as v0.1.0

            Experience with breathe and automodapi is summarized in https://dmtn-030.lsst.io (DM-7096)

            Show
            jsick Jonathan Sick added a comment - - edited documenteer released to PyPI as v0.1.10 lsst-sphinx-bootstrap-theme was released to PyPI as v0.1.0 Experience with breathe and automodapi is summarized in https://dmtn-030.lsst.io ( DM-7096 )

              People

              Assignee:
              jsick Jonathan Sick
              Reporter:
              jsick Jonathan Sick
              Watchers:
              Jonathan Sick
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.