Improve any role search for documents

[simaoafonso-pwt]

Is your feature request related to a problem? Please describe.
I have a somewhat large amount of code in an unsupported language documented on a Sphinx project. I have a document per function, and this works quite well for the most part.

Each of those documents are organized by section in a folder. For example, the file docs/general/FunctionName.rst starts with:

.. _FunctionName:

FunctionName
============

...

The cross references suffer from a weird issue:

• If I include the manual cross reference (.._FunctionName:), I get a warning for each file:

WARNING: more than one target found for 'any' cross-reference 'FunctionName': could be :doc:`FunctionName` or :std:ref:`FunctionName`

• If I remove the manual cross reference, the reference is not found.

To avoid the warning and the manual xref, I would need to change all references to:

`/general/FunctionName <FunctionName>`

This is just awful, I don't want to encode the "section" name on the reference, this is only a way to organize the functions.

Describe the solution you'd like

any should be smarter about resolving document cross references, by looking at all documents with a common suffix.

In my case, I know there won't be documents with the same name in different folders.

I think this might be too disruptive, it could be implemented as an option?

Describe alternatives you've considered
Mentioned above.

Is there any way to "link" a bunch of documents to the document root, to avoid the manual xref? Changing all references to /FunctionName is a possibility.

I opened #12739 to suppress these warnings.

Additional context

The default_role is set to any, and I have:

extensions.append('sphinx.ext.autosectionlabel')
autosectionlabel_prefix_document = True  # Prefix reference with document name

[electric-coder]

You don't provide an example of how you cross-reference so I get the impression you're making a mistake.

If I include the manual cross reference (.._FunctionName:)

That's not a cross-reference, it's:

.. _FunctionName:

FunctionName
============

an Internal hyperlink target above a section; that's a feature that's worked well for years. You'd reference it with :ref:`FunctionName` or :ref:`some text <FunctionName>` as explained in Cross-referencing arbitrary locations. So there's no example of you using the :any: role and instead the appropriate role is :ref: or :doc:.

The error message:

WARNING: more than one target found for 'any' cross-reference 'FunctionName': could be :doc:FunctionName or :std:ref:FunctionName

Suggests you're giving the document the same name as the internal hyperlink target, so the warning is correct and Sphinx should warn users when there's a name collision.

[simaoafonso-pwt]

My bad, that's right, it's an internal hyperlink target. I agree that ref is the right role to use, but any works well since it is one of the roles it picks up.

Suggests you're giving the document the same name as the internal hyperlink target, so the warning is correct and Sphinx should warn users when there's a name collision.

That's right, I agree that the warning is correct.

My question is if I do not include the internal hyperlink target, any does not pick up the doc name, even though it's has an unambigous suffix. In summary:

• Including the hyperlink target means there is a name collision
• Not including the hyperlink target means the document is not picked up

[electric-coder]

Including the hyperlink target means there is a name collision

You aren't correctly structuring your documentation, there's no point giving a section and a document the same name. But if you have such a use-case then make sure to choose the appropriate role.

any does not pick up the doc name, even though it's has an unambigous suffix.

Cross-references don't use file extensions. Items are cross-referenced by name; an .rst file becomes a "document" for Sphinx internally and thus has a name but not an extension and this is convenient because it makes the cross-referencing syntax homogeneous for all kinds of items, be it a class or a doc. Hence when writing :doc:`file_name` there's never an issue of having to wonder if you should write :doc:`file_name.rst` .

I've see dozens (likely hundreds) of users asking for :any: to magically solve all their problems, but if you declare two items with the same name having as only possible distinction the specific role then you have to choose the right role to make that distinction.

[simaoafonso-pwt]

You aren't correctly structuring your documentation, there's no point giving a section and a document the same name. But if you have such a use-case then make sure to choose the appropriate role.

Cross-references don't use file extensions. Items are cross-referenced by name; an .rst file becomes a "document" for Sphinx internally and thus has a name but not an extension and this is convenient because it makes the cross-referencing syntax homogeneous for all kinds of items, be it a class or a doc. Hence when writing :doc:`file_name` there's never an issue of having to wonder if you should write :doc:`file_name.rst`.

Yes, I understand that, the .rst extension is not the problem. What I mean is the document name is organized by folder, and I wanted to keep the folder organization, but reference them in a flat namespace.

Now that I'm think about this further, I think this is a request to change the doc role.

Here's a larger example:

• section1/
  • doc11.rst
  • doc12.rst
• section2/
  • doc21.rst
  • doc22.rst

I want to be able to use `doc11` to reach the document, even from other sections (on doc22 for example). doc only supports relative "paths", so from inside section2, I need to use `../section2/doc11`. Since I know that all document names are unambiguous, I wanted the doc role to search over all document names (but warn me if there are ambiguous names). Maybe this could be a new alldoc role?

[electric-coder]

You should direct your usage questions to Stack Overflow, see:

Get support

• Please verify that your question does not exist on StackOverflow (with the tag python-sphinx)

To me this seems like a chameleon-question because you haven't sufficiently researched or tested your solution. (I would hammer this thread closed in a heartbeat at Stack Overflow for lacking a minimal reproducible example, you haven't written a single cross-reference in the question so I'm not convinced that you actually tested anything you wrote.)

Maybe this could be a new alldoc role?

This thread is a usage question that's trying to disguise itself as a speculative feature-request.