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

          relates to

          Story - Created by Jira Software - do not edit or delete. Issue type for a user story. DM-15774 Initial Sphinx-based Task documentation for packages

          • Done

            Activity

            Ascending order - Click to sort in descending order
            Hide
            Permalink
            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.

            Show
            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.
            Hide
            Permalink
            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?

            Show
            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

              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.