Details
-
Type:
Story
-
Status: To Do
-
Resolution: Unresolved
-
Fix Version/s: None
-
Component/s: daf_butler, pipelines_lsst_io
-
Labels:
-
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
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.
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.