0

I want to add a cross reference using :ref: directive in Sphinx to a header in a specific file. The problem i have is that multiple RST file have similar heading structure so the headings are duplicated. So i have tried to get the :ref: work with autosectionlabel and i am having issues.

This works 'refer to my section <my_page.html#my_section>' where I have my_page.rst with the section header my_section.

However when i say :ref:'my_page:my_section' I get WARNING: undefined label

To make sure i have the correct relative path to my_page.rst, i also tried :doc:my_page and that works, so at least i know that :doc: works and the :ref: is not working

I looked through the answers here and i found this link Adding a cross-reference to a subheading or anchor in another page but the answers are not working for me.

mzjn
  • 48,958
  • 13
  • 128
  • 248
Kishore Vanapalli
  • 114
  • 9
  • Hello @KishoreVanapalli, use the [first solution in this answer](https://stackoverflow.com/a/19543591) the label is just a string you don't have to write file and section separated by a dot, like `page.section` you must however use an underscore at the beginning of the label, formally it works as a [reST hyperlink target](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#hyperlink-targets) – bad_coder Feb 09 '21 at 06:37
  • I haven't used autosection label, but the example in the answer you linked used a colon `:` instead of a dot `.` separating the page from the section. Notice the [autosection documentation](https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html) – bad_coder Feb 09 '21 at 06:42
  • @bad_coder, you mean to say add a label like `.. _my_section_label:` in the RST where my_section exists and use `:ref:my_section_label` ? I dont want to create custom labels. – Kishore Vanapalli Feb 09 '21 at 06:54
  • Have you tried with colon instead of dot? (e.g. separating `file:section`) – bad_coder Feb 09 '21 at 06:58
  • 1
    My question was a typo :) Yes it was `file:section`. That was a good catch by the way. Thank you for your details. – Kishore Vanapalli Feb 09 '21 at 07:04
  • No problem, always glad to help. I'm sorry the question had to be closed, but the important things is you found the solution you wanted (it takes some time learning to use cross-references effectively). – bad_coder Feb 09 '21 at 07:06
  • @bad_coder so the actual notation is `:ref:'{dir-path}/file_name:sec_name'` where `{dir-path}` is the relative path from config.py – Kishore Vanapalli Feb 09 '21 at 08:04

0 Answers0