RST Substitutions in docstrings
See original GitHub issueDescription
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 https://github.com/astropy/astropy/pull/10662#discussion_r527127005, 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
Issue Analytics
- State:
- Created 3 years ago
- Reactions:1
- Comments:10 (10 by maintainers)
Top Results From Across the Web
Reuse Content — RST | Sublime | GitHub documentation
For common, short content, use RST substitutions. For example, use a substitution for a product name. To print the product name in a...
Read more >reStructuredText Markup Specification - Docutils - SourceForge
The explicit markup syntax is used for footnotes, citations, hyperlink targets, directives, substitution definitions, and comments. An explicit markup block is ...
Read more >Have Sphinx replace docstring text - python - Stack Overflow
I want to use the | token, but they are reserved for global substitutions. I got around that by putting the following line...
Read more >reStructuredText Primer - Sphinx documentation
If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog or put them into a separate file...
Read more >flake8-rst-docstrings - PyPI
This is an MIT licensed flake8 plugin for validating Python docstrings markup as reStructuredText (RST) using the Python library docutils.
Read more >Top Related Medium Post
No results found
Top Related StackOverflow Question
No results found
Troubleshoot Live Code
Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start FreeTop Related Reddit Thread
No results found
Top Related Hackernoon Post
No results found
Top Related Tweet
No results found
Top Related Dev.to Post
No results found
Top Related Hashnode Post
No results found
Top GitHub Comments
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-L101I 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.