change documentation to reflect all code

Signed-off-by: Nathaniel Starkman (@nstarman) <nstarkman@protonmail.com>
astropy · May 19, 2021 · 470d1ba · 470d1ba
1 parent f7d2f81
commit 470d1ba
Show file tree

Hide file tree

Showing 3 changed files with 15 additions and 9 deletions.
diff --git a/docs/changes/11690.other.rst b/docs/changes/11690.other.rst
@@ -0,0 +1,5 @@
+In docstrings, Sphinx cross-reference targets now use intersphinx, even if the
+target is an internal link (``link`` is now ``'astropy:link``).
+When built in Astropy these links are interpreted as internal links. When built
+in affiliate packages, the link target is set by the key 'astropy' in the
+intersphinx mapping.
diff --git a/docs/changes/coordinates/11690.other.rst b/docs/changes/coordinates/11690.other.rst
diff --git a/docs/development/docguide.rst b/docs/development/docguide.rst
@@ -44,12 +44,6 @@ the standard Astropy docstring format.
 * All documentation should be written using the `Sphinx`_
   documentation tool.
 
-  + cross-reference links (``:ref:``, ``:doc:``, etc.), **including internal
-    Astropy links**, should use the `intersphinx format
-    <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_.
-    Note that in Astropy these internal links are to the current build, while
-    for affiliate packages these links resolve to the stable version.
-
 * ReST substitutions are centralized in ``docs/conf.py::rst_epilog`` for
   consistency across the documentation and docstrings. These should be used over
   custom redefinitions; and new substitutions should probably be placed there.
@@ -62,6 +56,16 @@ the standard Astropy docstring format.
 * Docstrings should follow the `numpydoc format
   <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
 
+* References in docstrings, **including internal Astropy links**, should use the
+  `intersphinx format
+  <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_.
+  For example a link to the Astropy section on unit equivalencies would be
+  `` :ref:`astropy:unit_equivalencies` ``.
+  When built in Astropy, links starting with 'astropy' resolve to the current
+  build. In affiliate packages using ``sphinx-astropy``'s intersphinx mapping,
+  the links resolve to the stable version of Astropy. For linking to the
+  development version, use the intersphinx target 'astropy-dev'.
+
 * Examples and/or tutorials are strongly encouraged for typical use-cases of a
   particular module or class.