RST Substitutions in docstrings

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 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

[saimn]

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

[saimn]

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.