Manual backport for astropy#11622 [ci skip]

Co-authored-by: Erik M. Bray <[email protected]>

docs/conf.py

@@ -66,6 +66,7 @@
 del intersphinx_mapping['astropy']
 
 # add any custom intersphinx for astropy
+intersphinx_mapping['astropy-dev'] = ('https://docs.astropy.org/en/latest/', None)  # noqa: F405
 intersphinx_mapping['pytest'] = ('https://pytest.readthedocs.io/en/stable/', None)
 intersphinx_mapping['ipython'] = ('https://ipython.readthedocs.io/en/stable/', None)
 intersphinx_mapping['pandas'] = ('https://pandas.pydata.org/pandas-docs/stable/', None)
@@ -275,6 +276,31 @@ def rstjinja(app, docname, source):
         source[0] = rendered
 
 
+def resolve_astropy_dev_reference(app, env, node, contnode):
+    """
+    Reference targets beginning with ``astropy-dev:`` are a special case.
+    If we are building the development docs it is a local ref targetting the
+    label ``astropy-dev:<label>``, but for stable docs it should be an
+    intersphinx resolution to the development docs.
+    See https://github.com/astropy/astropy/issues/11366
+    """
+
+    reftarget = node.get('reftarget')
+    if dev and reftarget is not None and reftarget.startswith('astropy-dev:'):
+        reftype = node.get('reftype')
+        refdoc = node.get('refdoc', app.env.docname)
+        reftarget = reftarget.split(':', 1)[1]
+        # Delegate to the ref node's original domain/target (typically :ref:)
+        try:
+            domain = app.env.domains[node['refdomain']]
+            return domain.resolve_xref(app.env, refdoc, app.builder,
+                                       reftype, reftarget, node, contnode)
+        except Exception:
+            pass
+
+        # Otherwise return None which should deletegate to intersphinx
+
+
 def setup(app):
     if sphinx_gallery is None:
         msg = ('The sphinx_gallery extension is not installed, so the '
@@ -291,3 +317,8 @@ def setup(app):
 
     # Generate the page from Jinja template
     app.connect("source-read", rstjinja)
+    # Set this to higher priority than intersphinx; this way when building
+    # dev docs astropy-dev: targets will go to the local docs instead of the
+    # intersphinx mapping
+    app.connect("missing-reference", resolve_astropy_dev_reference,
+                priority=400)

docs/index.rst

@@ -158,8 +158,9 @@ There are some additional tools, mostly of use for maintainers, in the
 
 {%else%}
 
-To read the developer documentation, you will need to go to the
-`latest developer version of the documentation <https://docs.astropy.org/en/latest/#developer-documentation>`__.
+To read the developer documentation, you will need to go to the :ref:`latest
+developer version of the documentation
+<astropy-dev:developer-docs>`.
 
 .. toctree::
    :maxdepth: 1

docs/install.rst

@@ -148,17 +148,9 @@ this case you may consider using the ``--user`` option to install the package
 into your home directory. You can read more about how to do this in the `pip
 documentation <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_.
 
-{% if is_development %}
-
-Alternatively, if you intend to do development on other software that uses
-``astropy``, such as an affiliated package, consider installing ``astropy`` into a :ref:`virtualenv<using-virtualenv>`.
-
-{%else%}
-
 Alternatively, if you intend to do development on other software that uses
-``astropy``, such as an affiliated package, consider installing ``astropy`` into a `virtualenv <https://docs.astropy.org/en/latest/development/workflow/virtualenv_detail.html>`__.
-
-{%endif%}
+``astropy``, such as an affiliated package, consider installing ``astropy``
+into a :ref:`virtualenv <astropy-dev:virtual_envs>`.
 
 Do **not** install ``astropy`` or other third-party packages using ``sudo``
 unless you are fully aware of the risks.
@@ -220,7 +212,8 @@ source code directory, or :ref:`running-tests` for more details.
 
 {%else%}
 
-See the `latest documentation on how to test your installed version of astropy <https://docs.astropy.org/en/latest/install.html#testing-an-installed-astropy>`__.
+See the :ref:`latest documentation on how to test your installed version of
+astropy <astropy-dev:testing_installed_astropy>`.
 
 {%endif%}
 
@@ -295,7 +288,7 @@ using this command::
 
    git clone --recursive git://github.com/astropy/astropy.git
 
-If you wish to participate in the development of ``astropy``, see
+If you wish to participate in the development of ``astropy``, see the
 :ref:`developer-docs`. This document covers only the basics necessary to
 installing ``astropy``.
 
@@ -542,7 +535,8 @@ need `pytest`_ to be installed for this to work.
 
 {%else%}
 
-See the `latest documentation on how to run the tests in a source checkout of astropy <https://docs.astropy.org/en/latest/install.html#testing-a-source-code-build-of-astropy>`__.
+See the :ref:`latest documentation on how to run the tests in a source
+checkout of astropy <astropy-dev:sourcebuildtest>`
 
 {%endif%}