blob: 29b1c2aed9737ce02cbcf2b4489f47c85775d527 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
.. highlight:: rst
:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title
==============================================================================
.. module:: sphinx.ext.autosectionlabel
:synopsis: Allow reference section its title.
.. versionadded:: 1.4
This extension allows you to refer sections its title. This affects to the
reference role (:rst:role:`ref`).
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.
Configuration
-------------
.. confval:: 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.
.. confval:: 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).
Debugging
---------
The ``WARNING: undefined label`` indicates that your reference in
:rst:role:`ref` is mis-spelled. Invoking :program:`sphinx-build` with ``-vvv``
(see :option:`-v`) will print all section names and the labels that have been
generated for them. This output can help finding the right reference label.
|
