Resolve intersphinx to own project as current build

[nstarman]

Is your feature request related to a problem? Please describe.

Motivated from astropy/astropy#11690

Take packages A and B, with package A as the core package and package B as an affiliate package.

When B subclasses a class from package A, docstrings can be inherited from the A class. If the docstring contains a reference, e.g.:doc:`/path/to` , then this link will incorrectly point to the documentation in the B package, not in the A package.

One option is to make the links intersphinx links, e.g. :doc:`A:/path/to` . While this is useful for the B package, now the link is broken for the A package, or at best refers to an old version of the docs: whatever is specified in the intersphinx mapping.

Describe the solution you'd like

Allow intersphinx references to the package being built to be "stripped" of the intersphinx portion and be resolved as local links. In the example above, :doc:`A:/path/to` -> :doc:`/path/to` when in package A. Now both packages A and B can use the same links. B gets an intersphinx link, A gets a link to the current build.

Describe alternatives you've considered

In astropy/astropy#11690 we implemented a bit of a hack by setting a function with higher priority than intersphinx to change the link types. While this works, a built-in solution would be better.

Additional context

• Resolve intersphinx to astropy as current build astropy/astropy#11690

[tk0miya]

It's a tough question. To share the docstring having special mark-up causes troubles sometimes. For example, sharing .. image:: directive call will cause the lack of the image file on documenting an inherited class. In this case, the reference on the parent project conflicts with the item on the B project.

First of all, let's start the case the owner of the A and B projects are the same. I think it's not impossible.

[nstarman]

Those are good points. Perhaps the best solution would be a setting / configuration parameter / something in intersphinx_mapping that lets one specify the intersphinx key that should be interpreted as the local project and "deintersphinxed".

So for project A it it might look like.

 intersphinx_mapping["A"] = ("std", None)   # (I think "std" is the local link name? correct me if I'm wrong)

Now project A can do in its docs

class SomeClass:
    ```Read more in :doc:A:`my-docs` ```

and it will resolve as if the docstring was Read more in :doc:`my-docs`

When project B makes its intersphinx mapping

 intersphinx_mapping["A"] = ('https://A.readthedocs.io/en/stable/', None)

and subclasses SomeClass

class SubSomeClass(SomeClass):
    # inherit the docstring

The doscstring will "just" work.

[tk0miya]

Now we introduces :external: role to make a cross-reference to the specific external document via intersphinx.
#9822

Could you try it please?

[pllim]

Thanks for the update, @tk0miya !

@nstarman , do we have to undo a bunch of astropy/astropy#11690 to take advantage of this new upstream feature?

[nstarman]

Thanks @tk0miya!
I'm trying to understand how this will work for us.
For a link in astropy, e.g. :ref:`astropy-constants-prior` , this resolves nicely to the current Astropy build.
What astropy/astropy#11690 did was to rig it so :ref:`astropy:astropy-constants-prior` also resolves to the current Astropy build (when built in Astropy) by effectively stripping the astropy: prefix. The advantage of these links over the ones without astropy: is that they can be used by 3rd-party packages and will still point to the Astropy docs.

With the new :external: role, how can Astropy have something like :ref:`astropy:astropy-constants-prior` where it resolves to the current Astropy build when being built in Astropy, but points to the Astropy docs when used by 3rd-party packages?

[jakobandersen]

Hmm, I think the new external is part of the solution, but as suggested in #9169 (comment) we probably need a way to have an intersphinx mapping which refers to the same project.
It should be trivial in external to simply not hijack such references.
That is, you would write

:external+astropy:ref:`astropy-constants-prior`

and then intersphinx_mapping in the parent project maps astropy to self, while derived projects maps it to whereever Astropy is located.

But as pointed out in #9169 (comment), this would not help for all cases of docstrings, and the parent package needs to have these external roles explicitly.

[jakobandersen]

A quick proposal: #10127
Works, e.g., with:
rst:

.. py:function:: sum()

- :py:func:`sum`, resolves to the local version
- :external:py:func:`sum`, resolves to the Python docs
- :external+python:py:func:`sum`, same as above
- :external+testInv:py:func:`sum`, resolves to the local version

and then conf.py having

extensions = [ 
    'sphinx.ext.intersphinx',
]
intersphinx_mapping = { 
    'python': ('https://docs.python.org/3', None),
}
intersphinx_self_mapping = "testInv"