diff --git a/CHANGES b/CHANGES index f425e20f08c..e3c91d72e01 100644 --- a/CHANGES +++ b/CHANGES @@ -15,6 +15,7 @@ Features added * #10840: One can cross-reference including an option value: ``:option:`--module=foobar```. Patch by Martin Liska. +* #10881: autosectionlabel: Record the generated section label to the debug log. Bugs fixed ---------- diff --git a/doc/usage/extensions/autosectionlabel.rst b/doc/usage/extensions/autosectionlabel.rst index caaa5db2663..b5b9b51a994 100644 --- a/doc/usage/extensions/autosectionlabel.rst +++ b/doc/usage/extensions/autosectionlabel.rst @@ -45,3 +45,12 @@ Configuration 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 ``-vv`` +(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. diff --git a/sphinx/ext/autosectionlabel.py b/sphinx/ext/autosectionlabel.py index ef9249e5b0f..7dc9ddaec69 100644 --- a/sphinx/ext/autosectionlabel.py +++ b/sphinx/ext/autosectionlabel.py @@ -40,6 +40,9 @@ def register_sections_as_label(app: Sphinx, document: Node) -> None: name = nodes.fully_normalize_name(ref_name) sectname = clean_astext(title) + logger.debug(__('section "%s" gets labeled as "%s"'), + ref_name, name, + location=node, type='autosectionlabel', subtype=docname) if name in domain.labels: logger.warning(__('duplicate label %s, other instance in %s'), name, app.env.doc2path(domain.labels[name][0]),