21

I have a problem with using Sphinx-doc's :ref: role, I put a label above a paragraph and then I try to link to that label from another doc but inside the same project.

The label I use in one document:

.. _hal_1k_1p:

And the ref I try to use to link to that label:

:ref:`Link title hal_1k_1p`

But I only get this error message when building the doc:

WARNING: undefined label: link title hal_1k_1p (if the link has no caption the label must precede a section header)

What am I doing wrong?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Raiu
  • 315
  • 1
  • 2
  • 6

2 Answers2

32

Okay, looking at :ref: you need to have this:

:ref:`Link title <ha1_1k_1p>`

to link to that label.

Ensure you have angle brackets surrounding your label like so: <label>

return42
  • 543
  • 3
  • 10
user1411260
  • 563
  • 4
  • 5
  • 1
    When i read the official docs they give this answer regarding my problem "Labels that aren’t placed before a section title can still be referenced to, but you must give the link an explicit title, using this syntax: :ref:`Link title `." But the problem is that they dont really give an exempel of how to implement it, So im kinda stuck – Raiu Sep 02 '15 at 18:47
  • 5
    also note that the label definition **does** include the `_` at the beginning while the label usage does **not** include the `_` character – Hubert Kario Oct 20 '19 at 18:39
2

First make sure that your ref is in the format:

Label:

.. _yourlabel:

Reference:

This is a reference to :ref:`yourlabel`.

or (if you want to give it a custom name)

This is a reference to :ref:`my very own label <yourlabel>`.

The label definition contains the leading underscore (_) while the reference doesn't! Also make sure that you didn't accidentally copy the colons from the label definition (:) to the reference.

If that doesn't help try switching languages back to english temporarily in your conf.py:

language = 'en'

If you see that this works you can switch back. Somehow this solved my problem. Maybe related to: https://github.com/sphinx-doc/sphinx/issues/1300

glades
  • 3,778
  • 1
  • 12
  • 34