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

Generate summaries of tasks' Python APIs for task documentation topics

    XMLWordPrintable

Details

    Description

      For the Sphinx-based task topic documentation, we want to be able to show the signature of the task's Python API (particularly its _init_ and run methods). This shouldn't replace the canonical source of documentation as generated by automodapi, but it should instead give users a quick summary and entrypoint into that API documentation.

      One scenario is to show the signatures of the tasks's constructor and methods, and make those signatures clickable so that a user can access the API docs quickly.

      Another approach might be to also show the full docstring of things like the constructor and run method.

      The best approach is TBD.

      Attachments

        Issue Links

          Activity

            Tried autoclass:

            .. autoclass:: lsst.pipe.tasks.assembleCoadd.AssembleCoaddTask
             :noindex:
             :members: run, runDataRef
            

            It's nice that autoclass has a way of producing API documentation with noindex so it doesn't clobber the noindex made by automodapi.

            The problem with this is that we likely want to abbreviate the API documentation that appears task topics.

            • The Task class's docstring will link to the task topic. It'll be a bit circular if that link appears in the task topic itself.
            • We don't necessarily want the task topic page to replace the API topics. We want the task topic page to focus on how to construct a Task and how to run that Task.

            We really want the task topic to serve as a bridge from the Task landscape to the Python API landscape.

            I'm looking into the autodoc APIs to see if there are bits I can pull out. Otherwise we might need to build our own Sphinx extension that generates summaries of Task APIs.

            jsick Jonathan Sick added a comment - Tried  autoclass : .. autoclass:: lsst.pipe.tasks.assembleCoadd.AssembleCoaddTask :noindex: :members: run, runDataRef It's nice that autoclass has a way of producing API documentation with noindex so it doesn't clobber the noindex made by automodapi . The problem with this is that we likely want to abbreviate the API documentation that appears task topics. The Task class's docstring will link to the task topic. It'll be a bit circular if that link appears in the task topic itself. We don't necessarily want the task topic page to replace the API topics. We want the task topic page to focus on how to construct a Task and how to run that Task. We really want the task topic to serve as a bridge from the Task landscape to the Python API landscape. I'm looking into the autodoc APIs to see if there are bits I can pull out. Otherwise we might need to build our own Sphinx extension that generates summaries of Task APIs.

            Perhaps we can create a customized Documenter, as in https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc/__init__.py and then create a autoclass-like directive out of that?

            jsick Jonathan Sick added a comment - Perhaps we can create a customized Documenter , as in https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autodoc/__init__.py and then create a autoclass -like directive out of that?

            People

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

              Dates

                Created:
                Updated:
                Resolved:

                Jenkins

                  No builds found.