python-sphinxcross-reference

Cross-reference to another page with Python-Sphinx


Hi whoever will read this!

I am writing a documentation webpage with Sphinx, and though I have been able to create nice cross-referencing in the same page following what is found on this guide, I now want to add in page A the reference to a subsection in page B.

I know that I can do so with an explicit external link, like:

`Link name <https://my.documentation.domain/path/to/page-B#subsection>`_

but can I do so with a cross-reference as well? It would be neater in my opinion. I tried :

:doc:`page_B:subsection`

and

:doc:`page_B#subsection`

but it is not recognized. Sorry if this is a dummy question but I did not find the answer on the internet. Thank you :)


Solution

  • Thank you @bad_coder and @Steve Piercy! So this question's answer is what I was looking for, but was not formulated in a way I could find it. For anyone who would end up here, what worked for me is :

    Define a target in page-A, by adding before the section title:

    .. _target name in page A:
    

    Refer to this target in page-B, simply with:

    :ref:`target name in page A`
    

    Note that you do not need to add page-A name, the reference will be automatically found.

    It also works to use a relative html link, but this is far less robust (it would break if section names are changing, for instance):

    `Link name <page_A.html#subsection>`_