Remove automatic table of contents

pep_sphinx_extensions/pep_processor/parsing/pep_parser.py

@@ -4,7 +4,7 @@
 
 from sphinx import parsers
 
-from pep_sphinx_extensions.pep_processor.transforms import pep_contents
+from pep_sphinx_extensions.pep_processor.transforms import pep_section_linker
 from pep_sphinx_extensions.pep_processor.transforms import pep_footer
 from pep_sphinx_extensions.pep_processor.transforms import pep_headers
 from pep_sphinx_extensions.pep_processor.transforms import pep_title
@@ -27,6 +27,6 @@ def get_transforms(self) -> list[type[transforms.Transform]]:
         return [
             pep_headers.PEPHeaders,
             pep_title.PEPTitle,
-            pep_contents.PEPContents,
+            pep_section_linker.PEPSectionLinker,
             pep_footer.PEPFooter,
         ]

pep_sphinx_extensions/pep_processor/transforms/pep_section_linker.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from docutils import nodes
+from docutils import transforms
+
+
+class PEPSectionLinker(transforms.Transform):
+    """Link section headings to themselves."""
+
+    default_priority = 720
+
+    def apply(self) -> None:
+        if not Path(self.document["source"]).match("pep-*"):
+            return  # not a PEP file, exit early
+        _link_section_headings(self.document[0][3:])  # skip PEP title, headers, and <hr/>
+
+
+def _link_section_headings(children: list[nodes.Node]):
+    for section in children:
+        if not isinstance(section, nodes.section):
+            continue
+
+        # remove all pre-existing hyperlinks in the title (e.g. PEP references)
+        title = section[0]
+        while (link_node := title.next_node(nodes.reference)) is not None:
+            link_node.replace_self(link_node[0])
+
+        title["refid"] = section["ids"][0]   # Add a link to self
+
+        _link_section_headings(section.children)  # recurse to sub-sections

pep_sphinx_extensions/pep_processor/transforms/pep_title.py

@@ -46,6 +46,9 @@ def apply(self) -> None:
         pep_title_node.extend(document_children)
         self.document.note_implicit_target(pep_title_node, pep_title_node)
 
+        # Add a horizontal rule after title and PEP headers
+        self.document[0].insert(2, nodes.transition())
+
 
 def _line_to_nodes(text: str) -> list[nodes.Node]:
     """Parse RST string to nodes."""