Repository navigation
RST Substitutions in docstrings #11063
Description
Description
In docs/conf.py it is possible to add often used substitutions to the rst_epilog variable. These substitutions can also be used in docstrings. I propose we replace many of the docstrings with their RST substitution counterparts, at least for very obvious substitutions like Unit and Quantity and SkyCoord, etc.
As @mhvk points out in #10662 (comment), we can define things like "Quantity-like" where a Column with a unit will work where a Quantity would too. Some of these, like where a string can replace a unit, might be a multiple RST replacement (see example below).
Example
docs/conf.py
rst_epilog += """
.. |Unit| replace:: :class:`~astropy.units.Unit`
.. |Unit.to| replace:: :meth:`~astropy.units.Unit.to` # descriptive
.. |Quantity| replace:: :class:`~astropy.units.Quantity`
.. |SkyCoord| replace:: :class:`~astropy.coordinates.SkyCoord`
.. |find_api_page| replace:: :func:`~astropy.find_api_page` # function
.. |Representation| replace:: :class:`~astropy.coordinates.BaseRepresentation` # simplification
.. |Differential| replace:: :class:`~astropy.coordinates.BaseDifferential` # simplification
.. |Quantity-like| replace:: Quantity-like # replacement invariant
.. |unit-like| replace:: :class:`~astropy.units.Unit` or str # multiple subs
"""
some_file.py
def func(x):
"""function
Parameters
——————
x : |Quantity|
"""
passReacted by Juan Luis Cano Rodríguez
Activity
Cadair commentedon Nov 23, 2020
I don't think the
.. class::replacements are worthwhile. Given I am pretty sure`.Quantity`alone will find the right class. (I recently discovered that shortcut, it finds the matching class in the obj inventory).nstarman commentedon Nov 23, 2020
does that also work for functions? in particular are they correctly appended with
()?Cadair commentedon Nov 23, 2020
No, the default is
:obj:so they don't get the()unless you do:meth:`.Quantity.to`I would guess.nstarman commentedon Nov 23, 2020
Still. That's a cool simplification! I wish they would advertise that on the ReST docs.
I'm trying to find how long the lookup takes. I recently timed my docs and docstrings with
:class:`x`take a fair bit longer to compile than those without, and that's a direct link.But if they take similarly long, then perhaps direct substitutions are not necessary for classes as they are only 1 character shorter.
But for functions, methods, and other things, #11063 (comment) suggests that substitutions might still be worthwhile.
mhvk commentedon Nov 23, 2020
@Cadair - this sounds intriguing! My goal for all this would be to find a way that is less verbose than what we have currently, so that the docstrings if seen in, say, an
ipythonsession, become more readable, yet still gives correct links in the sphinx build. In that respect, @nstarman's substitutions sounded good, as enclosing with|could just hint that it is something class like which one can find documentation for (like{..., ...}indicates a fixed set of options). A leading.to indicate a class would go quite a bit of the way, though I guess it could not handle the "*-like" category (maybe particularly useful for coordinate frames).A different question perhaps is whether we could adjust our sphinx machinery to just recognize particular names in
ParametersandReturnssections (which I think are special-cased already).saimn commentedon Nov 23, 2020
Another option is Numpydoc's XREF feature (
numpydoc_xref_param_type/numpydoc_xref_aliases: https://numpydoc.readthedocs.io/en/latest/install.html#sphinx-config-options) which can be used to cross-reference types without backticks, and with custom aliases, e.g. :https://github.com/musevlt/mpdaf/blob/d04c8674fdcaef01ab2900be569d8e543fb964ed/doc/conf.py#L88-L101
mhvk commentedon Nov 23, 2020
@saimn - yes, that was exactly what I was thinking of - so nice to know that it exists already!
nstarman commentedon Nov 30, 2020
@mhvk @saimn. That does seem the best solution.
Given the number of docstrings and the scope of this, is there a good module to start on first?
What should be on the list of substitutions?
mhvk commentedon Dec 1, 2020
@nstarman - how about just the
astropy.unitsmodule? Could just have the lower casequantityandunitthough in some casesunit-likemay be appropriate (e.g., where a string is allowed, though perhaps that is so often thatunitshould just directly go there).Sorry to be a bit vague, but I think it is one of those things where a trial may be needed to know what would really work best.
saimn commentedon Dec 1, 2020
I think the first step would be to try this feature with simple things like "array_like" to see if it slows down the documentation build, since we have a big documentation that already takes a lot of time to build.
Then I'm not sure if we want to provide aliases for common astropy classes like
|SkyCoord|, as we can already use`~astropy.coordinates.SkyCoord`, or even`SkyCoord`if it is imported in the module.