Adding a cross-reference to a subheading or anchor in another page

by

The expression “reST/Sphinx” makes the scope of the question unclear. Is it about reStructuredText in general and Sphinx, or only about reStructuredText as used in Sphinx (and not reStructuredText in general)? I’m going to cover both since people using RST are likely to run into both cases at some point:

Sphinx

Besides the domain-specific directives that can be used to link to various entities like classes (:class:) there’s the general :ref: directive, documented here. They give this example:

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

Although the general hyperlinking mechanism offered by RST does work in Sphinx, the documentation recommends against using it when using Sphinx:

Using ref is advised over standard reStructuredText links to sections (like Section title_) because it works across files, when section headings are changed, and for all builders that support cross-references.

RST, in General

The tools that convert RST files to HTML do not necessarily have a notion of collection. This is the case for instance if you rely on github to convert RST files to HTML or if you use a command line tool like rst2html. Unfortunately, the various methods to use to get the desired result vary depending on which tool you are using. For instance, if you use rst2html and you want file A.rst to link to a section named “Section” in file other.rst and you want the final HTML to work in a browser, then A.rst would contain:

`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.

You have to link to the final HTML file and you have to know what the id given to the section will be. If you want to do the same for a file served through github:

`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.

Here too you need to know the id given to the section. However, you link to the RST file because it is only upon accessing the RST file that the HTML is created. (At the time of writing this answer, accessing the HTML directly is not allowed.)

A complete example is available here.

More Related Contents:

  1. Format text in a link in reStructuredText
  2. How do I set up custom styles for reStructuredText, Sphinx, ReadTheDocs, etc.?
  3. Sorting display by class using sphinx with ‘autodoc’?
  4. How would I cross-reference a function generated by autodoc in Sphinx?
  5. Easiest way to merge a release into one JAR file
  6. Sphinx’s autodoc’s automodule having apparently no effect
  7. How do I document classes without the module name?
  8. Sphinx autodoc is not automatic enough
  9. knitr/rmarkdown/Latex: How to cross-reference figures and tables?
  10. Override function declaration in autodoc for sphinx
  11. Sphinx cannot find my python files. Says ‘no module named …’
  12. Highlight Menu Item when Scrolling Down to Section
  13. w3c html validation error – Section lacks heading. Consider using h2-h6 elements to add identifying headings to all sections
  14. Change file type association in PyCharm
  15. How do I document classes imported from other modules – hence without the declaration module’s name?
  16. Is there YAML syntax for sharing part of a list or map?
  17. Automatically document all modules recursively with Sphinx autodoc
  18. How to add custom css file to Sphinx?
  19. What do the &,
  20. sphinx-build fail – autodoc can’t import/find module
  21. How do I output a config value in a Sphinx .rst file?
  22. sphinx.ext.autodoc: Keeping names of constants in signature
  23. Keeping the API updated in Sphinx
  24. How to preserve line breaks when generating python docs using sphinx
  25. Simple cross import in python
  26. How to force Sphinx to use Python 3.x interpreter
  27. How to document Python packages using Sphinx
  28. How to use sphinx automodule and exposed functions in __init__
  29. Customize sphinxdoc theme
  30. How to express multiple types for a single parameter or a return value in docstrings that are processed by Sphinx?

Leave a Comment