rest
sphinx.ext.autosectionlabel
1.4
This extension allows you to refer sections its title. This affects to the reference role (:rstref
).
For example:
A Plain Title
-------------
This is the text of the section.
It refers to the section title, see :ref:`A Plain Title`.
Internally, this extension generates the labels for each section. If same section names are used in whole of document, any one is used for a target by default. The autosectionlabel_prefix_document
configuration variable can be used to make headings which appear multiple times but in different documents unique.
autosectionlabel_prefix_document
True to prefix each section label with the name of the document it is in, followed by a colon. For example, index:Introduction
for a section called Introduction
that appears in document index.rst
. Useful for avoiding ambiguity when the same section heading appears in different documents.
autosectionlabel_maxdepth
If set, autosectionlabel chooses the sections for labeling by its depth. For example, when set 1 to autosectionlabel_maxdepth
, labels are generated only for top level sections, and deeper sections are not labeled. It defaults to None
(disabled).
The WARNING: undefined label
indicates that your reference in :rstref
is mis-spelled. Invoking sphinx-build
with -vv
(see -v
) will print all section names and the labels that have been generated for them. This output can help finding the right reference label.