Thoughts on intersphinx vs local target names for :doc: cross-references

[Juan Luis Cano Rodríguez]

Hi all,

As part of the new tutorial I'm writing, I am learning more intricacies of how cross-references work in Sphinx. In particular, I found a couple of surprising behaviors with intersphinx [1], and I think Sphinx could improve the consistency in such cases.

I am editing the documentation of my dummy project, Lumache, that has intersphinx enabled, with a mapping to the Sphinx docs. In particular, I am editing a file that is in a subdirectory, say `doc/source/guides/new.rst`. If I insert a reference to the document `contents`, several things can happen:

- If I write :doc:`/contents`, it correctly inserts a reference to the `doc/source/contents.rst`, since it's an absolute path.

- If I write :doc:`contents`, it correctly inserts a reference to `doc/source/guides/contents.rst`, since it's a relative path.

- If I write :doc:`sphinx:contents`, it inserts a reference to https://www.sphinx-doc.org/en/master/contents.html, since that document is called `contents` in the inventory.

However, imagine now that I modify the Sphinx documentation itself. Then :doc:`contents` is context-dependent, since it's using a relative path!

In other words: :doc:`sphinx:contents` in my dummy project refers to an std:doc object called `contents` in the Sphinx inventory, whereas :doc:`contents` in Sphinx might refer to `contents`, `tutorial/contents`, or anything else depending on the directory.

The current logic of relative & absolute paths for :doc: cross-references is totally fine. Still, I think having to mentally think of a different logic when using intersphinx is confusing.

To fix this inconsistency, one would have to tell users to use :doc:`sphinx:/contents` instead. However, (1) at the moment this doesn't work, and (2) this is a breaking change.

In summary, I would like to ask the Sphinx devs what do they think about this (if it's not an inconsistency because I'm "thinking wrong", if it's an inconsistency but we have to live with it because there is no easy way to change it, or if it's an inconsistency but they see a way forward). In addition, whatever conclusion we reach, I would love to help documenting this better so we can point people to some reading material about the topic in the future.

[1] https://github.com/sphinx-doc/sphinx/pull/9424#discussion_r668985704

Cheers,

jua...@readthedocs.org

Read the Docs

[Juan Luis Cano Rodríguez]

I believe some or all of these points are being addressed by Jakob at https://github.com/sphinx-doc/sphinx/pull/9459. Thanks!