How to reference another page in project with section ID?

Question

This works fine as long as I don't need a specific section - and this seems to work: name <page.html>_, except if I repeat name Sphinx throws

WARNING: Duplicate explicit target name: "name"

and even if it's harmless, it populates the screen quickly in my application.

I'm aware of raw HTML-based workarounds, but that's a discouraged practice; is there a more "native" approach?

---

Example:

• `docs <package.html#module-package.callbacks>`_ (works)

• :doc:`docs <package.html#module-package.callbacks>` (doesn't)

• :doc:`docs <package#module-package.callbacks>` (doesn't)

Answer 1

I don't think it's a good approach to use intersphinx if your aim is cross-referencing your project internally.

At this point it has to be noticed: When using one of the autodoc directives like automodule or autoclass, that Python object is placed in the Sphinx index and can be cross-referenced.

But this raises a question: How to cross-reference ReST sections? It's considered an arbitrary location because they aren't objects, and they aren't inserted in the Sphinx index by the autodoc directives (or through a py domain declaration in your .rst).

Well, in that case there are 4 main options to consider (the last may be the least obvious, and thus the most important):

1. Use a ReST hyperlink targets directly above the section.
2. Use Python domain reference directly to the autodoc directive below the section.
3. Use a cross-reference to the document if the section sits on the top of the .rstfile.

Last but not least:

4. Consider you have 1 .rst file that documents one or several packages (lets say your_package.utils). Normal ReST rules have you place 1 section on the top of the file. But there isn't an automodule directive because, probably, the package is an empty __init__.py without a docstring...So what's the best solution in that case?

*****************
your_package.UTIL
*****************

.. py:module:: your_package.UTIL


Modules
=======

(...the usual stuff...)

OK!!! Now, by explicitly declaring your_package.util at above or below the ReST section as a Python module (or any Python object that may apply) what happens??? It gets inserted in the Sphinx index!!! Why is that important?? Because you can cross-reference it as a Python module (packages are, after all, modules) and don't have to cross-reference it as a document, or as a section. Which gives overall consistency to your documentation, index, and cross-referencing...

End result? You never see HTML or anchors..!! Sphinx manages/generates/indexes all of that for you. And that's what you really want. A complete abstraction layer.

Some people would raise objections:

• "You are putting Sphinx/ReST inside your Python docstrings (people don't know how to read that)."

Easily solved, put the plain English in the Docstring and ReST/Sphinx syntax in the .rst files (autodoc will join the parts).

• Others would object:"I want HTML in my ReST!"

Sure enough, but whenever you edit or refactor something it's doomed to become a pain. And who said normal Python/ReST developers looking at your stuff know anything -or want to look at- HTML or anchors?

So the soundest separation goes along these lines.

About using duplicate target names:

There's no real reason to use duplicate target names. A refactor done from your IDE is better served by unique target names. If you decide to move the ReST section the target above simply goes with it.

.. _this_section_without_duplicate_name:

*****************
Your ReST section
*****************

:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`

No anchors needed. Much cleaner and slick.