Autosectionlabel

[Giacometta Fritchman]

Internallythis extension generates the labels for each section. If samesection names are used in whole of document, any one is used for a target bydefault. The autosectionlabel_prefix_document configuration variable can beused to make headings which appear multiple times but in different documentsunique.

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 sectioncalled Introduction that appears in document index.rst. Useful foravoiding ambiguity when the same section heading appears in differentdocuments.

If set, autosectionlabel chooses the sections for labeling by its depth. Forexample, when set 1 to autosectionlabel_maxdepth, labels are generatedonly for top level sections, and deeper sections are not labeled. Itdefaults to None (disabled).

The WARNING: undefined label indicates that your reference inref is mis-spelled. Invoking sphinx-build with -vvv(see -v) will print all section names and the labels that have beengenerated for them. This output can help finding the right reference label.

sphinx.ext.autosectionlabel automatically creates labels for every sectionof every page in the project. This can reduce manual work and can increaseconsistency. However, with this feature enabled, there are a couple ofdownsides.

Once you use the autosectionlabel extension new in version 1.4Sphinx will detect duplicate labels, in contrast with Implicit Hyperlink Targetsautolabel define a new label for each section, so if you have manually put a labelbefore a section title which is identical to the title, it will be detected asduplicate.

These duplicate are harmless since they reference the same point. But some title in manydocument can be identical, you can have many introduction or conclusion in differentparts. The duplicate may be problematic as any one can be matched by a reference. Todisembiguate the labels there is an configuration option beginning version 1.6autosectionlabel_prefix_document which prefix the automatic labels with with thename of the document it is in, followed by a colon.

3a8082e126