Merge branch 'master' into c-domain-speedup

Author: donaldh

.flake8

@@ -2,8 +2,10 @@
 max-line-length = 95
 ignore =
     E116,
+    E203,
     E241,
     E251,
+    E501,
     E741,
     W503,
     W504,
@@ -29,5 +31,3 @@ exclude =
     doc/_build/*,
     sphinx/search/*,
     doc/usage/extensions/example*.py,
-per-file-ignores =
-    tests/*: E501

.github/workflows/lint.yml

@@ -85,16 +85,7 @@ jobs:
         python -m pip install --upgrade pip
         python -m pip install --upgrade sphinx-lint
     - name: Lint documentation with sphinx-lint
-      run: >
-        sphinx-lint
-        --enable line-too-long
-        --max-line-length 85 
-        AUTHORS.rst
-        CHANGES.rst
-        CODE_OF_CONDUCT.rst
-        CONTRIBUTING.rst
-        README.rst
-        doc/
+      run: make doclinter
 
   twine:
     runs-on: ubuntu-latest

.ruff.toml

@@ -426,37 +426,23 @@ forced-separate = [
 preview = true
 quote-style = "single"
 exclude = [
-    "sphinx/__init__.py",
     "sphinx/addnodes.py",
     "sphinx/application.py",
     "sphinx/builders/**/*",
     "sphinx/cmd/**/*",
     "sphinx/config.py",
-    "sphinx/deprecation.py",
     "sphinx/directives/**/*",
     "sphinx/domains/**/*",
     "sphinx/environment/**/*",
-    "sphinx/errors.py",
-    "sphinx/events.py",
     "sphinx/ext/**/*",
-    "sphinx/extension.py",
-    "sphinx/highlighting.py",
-    "sphinx/io.py",
-    "sphinx/jinja2glue.py",
-    "sphinx/locale/__init__.py",
-    "sphinx/parsers.py",
-    "sphinx/project.py",
     "sphinx/pycode/**/*",
     "sphinx/pygments_styles.py",
     "sphinx/registry.py",
-    "sphinx/roles.py",
     "sphinx/search/**/*",
     "sphinx/templates/**/*",
     "sphinx/testing/**/*",
-    "sphinx/theming.py",
     "sphinx/transforms/**/*",
     "sphinx/util/**/*",
-    "sphinx/versioning.py",
     "sphinx/writers/**/*",
     "tests/certs/**/*",
     "tests/conftest.py",
@@ -485,6 +471,4 @@ exclude = [
     "tests/test_util/**/*",
     "tests/test_versioning.py",
     "tests/test_writers/**/*",
-    "tests/utils.py",
-    "utils/**/*",
 ]

CHANGES.rst

@@ -58,10 +58,9 @@ type-check:
 
 .PHONY: doclinter
 doclinter:
-	@sphinx-lint --enable all --max-line-length 85 --disable triple-backticks \
-	             -i CHANGES.rst -i LICENSE.rst -i EXAMPLES.rst \
-	             $(addprefix -i doc/, _build _static _templates _themes) \
-	             *.rst doc/ 2>&1 | sort -V
+	@sphinx-lint --enable all --disable triple-backticks --max-line-length 85 --sort-by filename,line \
+			     $(addprefix -i doc/, _build _static _templates _themes) \
+	             AUTHORS.rst CHANGES.rst CODE_OF_CONDUCT.rst CONTRIBUTING.rst README.rst doc/
 
 .PHONY: test
 test:

Makefile

@@ -1,14 +1,17 @@
 from docutils import nodes
 from docutils.parsers.rst import Directive
 
+from sphinx.application import Sphinx
+from sphinx.util.typing import ExtensionMetadata
+
 
 class HelloWorld(Directive):
     def run(self):
         paragraph_node = nodes.paragraph(text='Hello World!')
         return [paragraph_node]
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_directive('helloworld', HelloWorld)
 
     return {

doc/development/tutorials/examples/helloworld.py

@@ -3,10 +3,12 @@
 from docutils.parsers.rst import directives
 
 from sphinx import addnodes
+from sphinx.application import Sphinx
 from sphinx.directives import ObjectDescription
 from sphinx.domains import Domain, Index
 from sphinx.roles import XRefRole
 from sphinx.util.nodes import make_refnode
+from sphinx.util.typing import ExtensionMetadata
 
 
 class RecipeDirective(ObjectDescription):
@@ -153,7 +155,7 @@ def add_recipe(self, signature, ingredients):
         self.data['recipes'].append((name, signature, 'Recipe', self.env.docname, anchor, 0))
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_domain(RecipeDomain)
 
     return {

doc/development/tutorials/examples/recipe.py

@@ -1,8 +1,10 @@
 from docutils import nodes
 from docutils.parsers.rst import Directive
 
+from sphinx.application import Sphinx
 from sphinx.locale import _
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
 
 
 class todo(nodes.Admonition, nodes.Element):
@@ -111,7 +113,7 @@ def process_todo_nodes(app, doctree, fromdocname):
         node.replace_self(content)
 
 
-def setup(app):
+def setup(app: Sphinx) -> ExtensionMetadata:
     app.add_config_value('todo_include_todos', False, 'html')
 
     app.add_node(todolist)

doc/development/tutorials/examples/todo.py

@@ -35,3 +35,9 @@ Utility components
 
 .. autoclass:: sphinx.events.EventManager
    :members:
+
+Utility types
+-------------
+
+.. autoclass:: sphinx.util.typing.ExtensionMetadata
+   :members:

doc/extdev/utils.rst

@@ -197,6 +197,14 @@ To run JavaScript tests, use ``npm``::
     npm install
     npm run test
 
+.. tip::
+
+  ``karma`` requires a Firefox binary to use as a test browser.
+
+  For Unix-based systems, you can specify the path to the Firefox binary using::
+
+    FIREFOX_BIN="/Applications/Firefox.app/Contents/MacOS/firefox" npm test
+
 New unit tests should be included in the ``tests`` directory where
 necessary: