1749469 - Generate labels for all headings

Status: NEW

(Developer Infrastructure :: Source Documentation, enhancement)

Description

[James Graham [:jgraham]]

In the conf.py file we currently have autosectionlabel_max_depth = 1 so we only generate labels for top level headings. But that seems rather pointless since linking to a whole document doesn't require a label at all. The reason for the setting is that labels by default share a global namespace in sphinx and each auto-generated heading label by default is just the text of the heading. So the default configuration means that we need to have globally unique subheadings across all docs in the tree, or we get ambiguous label names. That's clearly not reasonable.

The right fix here seems to be setting autosectionlabel_prefix_document = True so that the generated label names are prefixed with the document path i.e. a heading foo at sphinx path path/to/doc generates a label like path/to/doc:foo. Then subheading names only need to be unique within a given document, which is much more tractable.

Unfortunately fixing this requires fixing all existing uses of the autogenerated labels to include the prefix. So it's a three-step process:

• Update the config.py as described above.
• Fix all the WARNING: undefined label: warnings in the build output (I currently see a little over 200 of these with the setting flipped).
• Add the WARNING: undefined label: warning to the fatal warnings list in config.yaml so that we don't introduce more broken links in the future.