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

Add documentation system for StorageClass definitions

    XMLWordPrintable

    Details

    • Team:
      Architecture
    • Urgent?:
      No

      Description

      The configuration entries in daf_butler's storageClasses.yaml effectively define important Python APIs, both for users calling Butler.get with parameters and/or components, and Formatter implementations that need to support these.  But right now there's no way to document these aside from YAML comments (and we don't even do that much).

      We should probably add some dedicated documentation string entries to the YAML schema, and work out a way to make use of these in Sphinx.

        Attachments

          Activity

          Hide
          jsick Jonathan Sick added a comment - - edited

          If someone can sketch out what the documentation should look like (something like a mocked up Google docs page printed to PDF) and where the data comes from (which I understand is the first part of this ticket) I can provide the infrastructure on the Sphinx side.

          Show
          jsick Jonathan Sick added a comment - - edited If someone can sketch out what the documentation should look like (something like a mocked up Google docs page printed to PDF) and where the data comes from (which I understand is the first part of this ticket) I can provide the infrastructure on the Sphinx side.
          Hide
          jbosch Jim Bosch added a comment -

          I think the output documentation format for a StorageClass could probably be described pretty cleanly in terms of numpydoc structure's we're already familiar with:

          • the usual single-sentence short description and slightly longer summary below that;
          • an optional "base StorageClass" link analogous to the base class for Python class documentation (but with the target another StorageClass);
          • a non-optional "pytype" link near that (which would actually have a Python type as a target - but frequently one "downstream" terms of EUPS dependencies, in case that's a potential problem);
          • a "Parameters" section that's exactly like those for Python callables;
          • a "Components" section whose entries are documented exactly like Python properties, except that instead of the type being a Python type, it'd be another StorageClass;
          • a "Notes" section for more extended descriptions.

           

          Show
          jbosch Jim Bosch added a comment - I think the output documentation format for a StorageClass could probably be described pretty cleanly in terms of numpydoc structure's we're already familiar with: the usual single-sentence short description and slightly longer summary below that; an optional "base StorageClass" link analogous to the base class for Python class documentation (but with the target another StorageClass); a non-optional "pytype" link near that (which would actually have a Python type as a target - but frequently one "downstream" terms of EUPS dependencies, in case that's a potential problem); a "Parameters" section that's exactly like those for Python callables; a "Components" section whose entries are documented exactly like Python properties, except that instead of the type being a Python type, it'd be another StorageClass; a "Notes" section for more extended descriptions.  

            People

            Assignee:
            Unassigned Unassigned
            Reporter:
            jbosch Jim Bosch
            Watchers:
            Jim Bosch, Jonathan Sick, Tim Jenness
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Dates

              Created:
              Updated:

                Jenkins

                No builds found.