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

            Activity

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