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|
"""
pass
Description
In
docs/conf.pyit is possible to add often used substitutions to therst_epilogvariable. 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 likeUnitandQuantityandSkyCoord, 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
some_file.py