docstring updating #118
docstring updating #118
Conversation
| exptime : `float` | ||
| The exposure time to use per visit (seconds). | ||
| Default 29.2 | ||
| filter1s : `list` of `str` |
There was a problem hiding this comment.
list [str] rather than list of str (https://developer.lsst.io/python/numpydoc.html#py-docstring-parameter-types-sequences)
| HA_min(_max) : float | ||
| footprints : `rubin_scheduler.scheduler.utils.footprints.Footprints` | ||
| The footprints to be used. | ||
| night_pattern : `list` of `bool` |
| The weight on basis function that tries to stay avoid filter changes. | ||
| Default 3.0 (uniteless). |
| exptime : `float` | ||
| The exposure time to use per visit (seconds). | ||
| Default 29.2 | ||
| filter1s : `list` of `str` |
| nside : `int` | ||
| The HEALpix nside to use. Defaults to DEFAULT_NSIDE | ||
| filtername : `str` | ||
| The filter name for the first observation. Default "g". |
There was a problem hiding this comment.
Where we have a default value, it will show up in the docstring when this is built in the docs (see first screenshot). Because the docstring and the call are right next to each other, we don't have to repeat the default values in the docstring (and, as you can see in the second screenshot, it can make it all look messier).
I think if we're using None so that it defaults to some other value within the code, that "Default None will be set to xxxx" is useful, or it can be useful to know if we're setting the default for a good reason that other people should know (and then probably not change) - but otherwise we should probably get out of the habit of repeating our defaults.
There was a problem hiding this comment.
But if you pull up the docstring from the command line or in a notebook the call signature and the relevant section of the docstring can get totally separated.
There was a problem hiding this comment.
I guess I was thinking that
is still less readable than this (where removing the additional Default lines means that the whole thing is shorter)
My main problem is that the defaults that are in these sections tend to get outdated. If these are kept up to date, I'll be ok.
yoachim
force-pushed
the
u/yoachim/doc-formatting
branch
from
d384db2
to
813e633
Compare
Lots of docstring formatting in example_scheduler.py