Don’t Use Auto Section Label#
sphinx.ext.autosectionlabel automatically creates labels for every section
of every page in the project. This can reduce manual work and can increase
consistency. However, with this feature enabled, there are a couple of
We must enable
autosectionlabel_prefix_documentor we would not be allowed to have any two sections that share the same name. Eg. There couldn’t be two decision docs with a
Contextsection. This would result in an error (technically a warning but we treat all warnings as errors to miss some very important warnings.)
Even with document prefixing, you can’t have the same section name between two different sections in the same document. We run into this with our release notes where both the
Learner Experiencesections might talk about the same feature (
Open Response Assessmentsfor example).
The errors that occur from the automatic labels are confusing and hard to debug if you aren’t already familiar with auto labeling.
We will not use the autosectionlabel extension to create labels. Instead we’ll expect writers to manually create labels for any topics they wish to cross link to.