Undefined label: … (if the link has no caption the label must precede a section header)#

Symptoms#

Sphinx build failed with error similar to the following:

index.rst:4: WARNING: undefined label: foo (if the link has no caption the
label must precede a section header)

Reference :ref: points to non-existing label.

The document contains :ref: reference to cmd-options label, but a label doesn’t exist in the document either project.

Welcome
=======

For full list, see :ref:`cmd-options`.

Add missing label .. _cmd-options: before respective place.

Welcome!
========

See also :ref:`cmd-options`.

.. _cmd-options:

Commandline options
-------------------

Foo has many many many options.

Label may be added even in different document, e.g. reference.rst.

Reference
==========

...a lot of text...

.. _cmd-options:

Commandline options
--------------------

Foo has many many many options.