Upgrade Sphinx (#6624)

docs/_ext/scrapydocs.py

@@ -1,63 +1,67 @@
 # pylint: disable=import-error
+from collections.abc import Sequence
 from operator import itemgetter
+from typing import Any, TypedDict
 
 from docutils import nodes
+from docutils.nodes import Element, General, Node, document
 from docutils.parsers.rst import Directive
-from docutils.parsers.rst.roles import set_classes
+from sphinx.application import Sphinx
 from sphinx.util.nodes import make_refnode
 
 
-class settingslist_node(nodes.General, nodes.Element):
+class SettingData(TypedDict):
+    docname: str
+    setting_name: str
+    refid: str
+
+
+class SettingslistNode(General, Element):
     pass
 
 
 class SettingsListDirective(Directive):
-    def run(self):
-        return [settingslist_node("")]
+    def run(self) -> Sequence[Node]:
+        return [SettingslistNode()]
 
 
-def is_setting_index(node):
-    if node.tagname == "index" and node["entries"]:
+def is_setting_index(node: Node) -> bool:
+    if node.tagname == "index" and node["entries"]:  # type: ignore[index,attr-defined]
         # index entries for setting directives look like:
         # [('pair', 'SETTING_NAME; setting', 'std:setting-SETTING_NAME', '')]
-        entry_type, info, refid = node["entries"][0][:3]
+        entry_type, info, refid = node["entries"][0][:3]  # type: ignore[index]
         return entry_type == "pair" and info.endswith("; setting")
     return False
 
 
-def get_setting_target(node):
-    # target nodes are placed next to the node in the doc tree
-    return node.parent[node.parent.index(node) + 1]
-
-
-def get_setting_name_and_refid(node):
+def get_setting_name_and_refid(node: Node) -> tuple[str, str]:
     """Extract setting name from directive index node"""
-    entry_type, info, refid = node["entries"][0][:3]
+    entry_type, info, refid = node["entries"][0][:3]  # type: ignore[index]
     return info.replace("; setting", ""), refid
 
 
-def collect_scrapy_settings_refs(app, doctree):
+def collect_scrapy_settings_refs(app: Sphinx, doctree: document) -> None:
     env = app.builder.env
 
     if not hasattr(env, "scrapy_all_settings"):
-        env.scrapy_all_settings = []
-
-    for node in doctree.traverse(is_setting_index):
-        targetnode = get_setting_target(node)
-        assert isinstance(targetnode, nodes.target), "Next node is not a target"
+        emptyList: list[SettingData] = []
+        env.scrapy_all_settings = emptyList  # type: ignore[attr-defined]
 
+    for node in doctree.findall(is_setting_index):
         setting_name, refid = get_setting_name_and_refid(node)
 
-        env.scrapy_all_settings.append(
-            {
-                "docname": env.docname,
-                "setting_name": setting_name,
-                "refid": refid,
-            }
+        env.scrapy_all_settings.append(  # type: ignore[attr-defined]
+            SettingData(
+                docname=env.docname,
+                setting_name=setting_name,
+                refid=refid,
+            )
         )
 
 
-def make_setting_element(setting_data, app, fromdocname):
+def make_setting_element(
+    setting_data: SettingData, app: Sphinx, fromdocname: str
+) -> Any:
     refnode = make_refnode(
         app.builder,
         fromdocname,
@@ -73,22 +77,56 @@ def make_setting_element(setting_data, app, fromdocname):
     return item
 
 
-def replace_settingslist_nodes(app, doctree, fromdocname):
+def replace_settingslist_nodes(
+    app: Sphinx, doctree: document, fromdocname: str
+) -> None:
     env = app.builder.env
 
-    for node in doctree.traverse(settingslist_node):
+    for node in doctree.findall(SettingslistNode):
         settings_list = nodes.bullet_list()
         settings_list.extend(
             [
                 make_setting_element(d, app, fromdocname)
-                for d in sorted(env.scrapy_all_settings, key=itemgetter("setting_name"))
+                for d in sorted(env.scrapy_all_settings, key=itemgetter("setting_name"))  # type: ignore[attr-defined]
                 if fromdocname != d["docname"]
             ]
         )
         node.replace_self(settings_list)
 
 
-def setup(app):
+def source_role(
+    name, rawtext, text: str, lineno, inliner, options=None, content=None
+) -> tuple[list[Any], list[Any]]:
+    ref = "https://github.com/scrapy/scrapy/blob/master/" + text
+    node = nodes.reference(rawtext, text, refuri=ref, **options)
+    return [node], []
+
+
+def issue_role(
+    name, rawtext, text: str, lineno, inliner, options=None, content=None
+) -> tuple[list[Any], list[Any]]:
+    ref = "https://github.com/scrapy/scrapy/issues/" + text
+    node = nodes.reference(rawtext, "issue " + text, refuri=ref)
+    return [node], []
+
+
+def commit_role(
+    name, rawtext, text: str, lineno, inliner, options=None, content=None
+) -> tuple[list[Any], list[Any]]:
+    ref = "https://github.com/scrapy/scrapy/commit/" + text
+    node = nodes.reference(rawtext, "commit " + text, refuri=ref)
+    return [node], []
+
+
+def rev_role(
+    name, rawtext, text: str, lineno, inliner, options=None, content=None
+) -> tuple[list[Any], list[Any]]:
+    ref = "http://hg.scrapy.org/scrapy/changeset/" + text
+    node = nodes.reference(rawtext, "r" + text, refuri=ref)
+    return [node], []
+
+
+def setup(app: Sphinx) -> None:
     app.add_crossref_type(
         directivename="setting",
         rolename="setting",
@@ -114,36 +152,8 @@ def setup(app):
     app.add_role("issue", issue_role)
     app.add_role("rev", rev_role)
 
-    app.add_node(settingslist_node)
+    app.add_node(SettingslistNode)
     app.add_directive("settingslist", SettingsListDirective)
 
     app.connect("doctree-read", collect_scrapy_settings_refs)
     app.connect("doctree-resolved", replace_settingslist_nodes)
-
-
-def source_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    ref = "https://github.com/scrapy/scrapy/blob/master/" + text
-    set_classes(options)
-    node = nodes.reference(rawtext, text, refuri=ref, **options)
-    return [node], []
-
-
-def issue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    ref = "https://github.com/scrapy/scrapy/issues/" + text
-    set_classes(options)
-    node = nodes.reference(rawtext, "issue " + text, refuri=ref, **options)
-    return [node], []
-
-
-def commit_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    ref = "https://github.com/scrapy/scrapy/commit/" + text
-    set_classes(options)
-    node = nodes.reference(rawtext, "commit " + text, refuri=ref, **options)
-    return [node], []
-
-
-def rev_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
-    ref = "http://hg.scrapy.org/scrapy/changeset/" + text
-    set_classes(options)
-    node = nodes.reference(rawtext, "r" + text, refuri=ref, **options)
-    return [node], []

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx==6.2.1
+sphinx==8.1.3
 sphinx-hoverxref==1.4.2
 sphinx-notfound-page==1.0.4
 sphinx-rtd-theme==3.0.2