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?