diff --git a/exts/ferrocene_spec/__init__.py b/exts/ferrocene_spec/__init__.py index 1b4f5977..e2298b05 100644 --- a/exts/ferrocene_spec/__init__.py +++ b/exts/ferrocene_spec/__init__.py @@ -36,6 +36,7 @@ def is_empty(data): def setup(app): + path_id_sorting() app.add_domain(SpecDomain) definitions.setup(app) paragraph_ids.setup(app) @@ -62,3 +63,26 @@ def setup(app): # - 1: changed how informational sections and pages are stored "env_version": "1", } + +# By default this transform sorts all ids of the form `id[0-9]+` to the end. +# Our IDs are section name and fls_ id pairs, so in some cases this transform +# will instead sort the section name to the back, but not always! +# So we patch the transform instead so that our fls ids are sorted to the back. +# In addition to that we normalize them, as sphinx turns the `_` in `fls_{id}` +# into `fls-{id}` which can break the link check from working correctly. +def path_id_sorting(): + def sort_and_patch_underscore(self, **kwargs) -> None: + from docutils import nodes + + for node in self.document.findall(nodes.section): + for n, id in enumerate(node["ids"]): + if id.startswith("fls-"): + node["ids"][n] = id[:3] + "_" + id[4:] + # sort the fls id to the back + if len(node["ids"]) > 1 and node["ids"][0].startswith("fls_"): + node["ids"] = node["ids"][1:] + [node["ids"][0]] + + from sphinx.transforms import SortIds + + SortIds.apply = sort_and_patch_underscore +