Add debug logging to autosectionlabel

CHANGES

@@ -12,6 +12,8 @@ Deprecated
 
 Features added
 --------------
+* #10881: make debugging automatically generated section labels by
+  ``sphinx.ext.autosectionlabel`` easier.
 
 * #10840: One can cross-reference including an option value: ``:option:`--module=foobar```.
   Patch by Martin Liska.

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.

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]),