Override generation of id & href attributes for API documentation

This will replace dots with underscores in qualified names of Python modules & functions (e.g. `mypackage.mymodule.myfunc`), allowing ScrollSpy to identify these tags as navigation targets.

Addresses #1207 and fixes #1026

src/pydata_sphinx_theme/translator.py

@@ -58,3 +58,26 @@ def visit_table(self, node):
 
         tag = self.starttag(node, "table", CLASS=" ".join(classes), **atts)
         self.body.append(tag)
+
+    def visit_section(self, node):
+        """Override default behavior to replace dots with underscores in the ``id`` attribute of documented modules."""
+        # NOTE: This will modify the `id` attribute of HTML `<section>` tags, e.g. where Python modules are documented
+        if "ids" in node:
+            node["ids"] = [id_.replace(".", "_") for id_ in node["ids"]]
+        super().visit_section(node)
+
+    def visit_reference(self, node):
+        """Override default behavior to replace dots with underscores in ``href`` attributes."""
+        # NOTE: This will modify the `href` attribute of HTML `<a>` tags, e.g. the sidebar links
+        if "refuri" in node:
+            if "." in node["refuri"]:
+                node["refuri"] = node["refuri"].replace(".", "_")
+        super().visit_reference(node)
+
+    def visit_desc_signature(self, node):
+        """Replace dots with underscores in the ``id`` attribute of documented Python function signatures."""
+        # NOTE: This will modify the `id` attribute of HTML `<dt>` tags, where Python functions are documented
+        ids = node["ids"]
+        for i, id_ in enumerate(ids):
+            ids[i] = id_.replace(".", "_")
+        super().visit_desc_signature(node)