Adopt ruff 0.16 and its default rule set

CHANGES

@@ -18,6 +18,28 @@ $ uv add gp-sphinx --prerelease allow
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
+### Development
+
+#### Lint toolchain: ruff 0.16
+
+Minimum `ruff>=0.16.0` (was unpinned), so contributors and CI agree on
+which diagnostics fire. See the
+[release announcement](https://astral.sh/blog/ruff-v0.16.0).
+
+`ruff format` now formats Python code blocks embedded in Markdown, which
+reflows snippets in the READMEs and docs pages. Contributors who run the
+formatter on an older ruff will see those blocks revert, so upgrade
+before committing.
+
+Linting now runs ruff's default rule set alongside the linters this
+workspace picks explicitly. An explicit `select` replaces that default
+set rather than adding to it, so the config uses `extend-select`; the
+set is much larger than the old selection, and contributors will see
+diagnostics from linters the workspace never named. Rules that flag a
+deliberate idiom — blind excepts guarding a docs build against foreign
+code, `exec` in the suites that synthesise test modules — carry a scoped
+per-file ignore with its reasoning in `pyproject.toml`. (#73)
+
 ## gp-sphinx 0.0.1a36 (2026-07-26)
 
 gp-sphinx 0.0.1a36 makes a class that documents its fields in an

README.md

@@ -25,6 +25,7 @@ Replace your `docs/conf.py` with:
 
 ```python
 """Sphinx configuration for my-project."""
+
 from __future__ import annotations
 
 from gp_sphinx.config import merge_sphinx_config

docs/_ext/package_reference.py

@@ -458,10 +458,8 @@ def _repository_url_from_package_json(manifest: dict[str, t.Any]) -> str:
         return repo
     if isinstance(repo, dict):
         url = str(repo.get("url", ""))
-        if url.startswith("git+"):
-            url = url[len("git+") :]
-        if url.endswith(".git"):
-            url = url[: -len(".git")]
+        url = url.removeprefix("git+")
+        url = url.removesuffix(".git")
         return url
     return ""
 
@@ -937,14 +935,18 @@ def maturity_badge(maturity: str) -> str:
     (
         "autodoc",
         "Autodoc extensions",
-        "Domain-specific autodoc extensions: each adds directives that "
-        "generate documentation from a particular source-construct family.",
+        (
+            "Domain-specific autodoc extensions: each adds directives that "
+            "generate documentation from a particular source-construct family."
+        ),
     ),
     (
         "ux",
         "UX components",
-        "Badge primitives, layout presenters, and other shared "
-        "rendering helpers consumed by the autodoc family.",
+        (
+            "Badge primitives, layout presenters, and other shared "
+            "rendering helpers consumed by the autodoc family."
+        ),
     ),
     (
         "highlighting",
@@ -954,8 +956,10 @@ def maturity_badge(maturity: str) -> str:
     (
         "build-seo",
         "Build & SEO",
-        "PEP 517 backends, build orchestration, and crawl-indexing "
-        "extensions auto-loaded by gp-sphinx when ``docs_url`` is set.",
+        (
+            "PEP 517 backends, build orchestration, and crawl-indexing "
+            "extensions auto-loaded by gp-sphinx when ``docs_url`` is set."
+        ),
     ),
 )
 
@@ -1612,10 +1616,12 @@ def _live_signature_markdown(package_name: str) -> str:
     # in E2). Directives that emit H1 via parse_text_to_nodes do NOT
     # set the page title — Sphinx's title extraction has already run.
     lines = [
-        f"Public callables in `{record.module_name}` rendered from the "
-        "running interpreter at docs-build time. Drift between this "
-        "block and the prose elsewhere on the page indicates a stale "
-        "docstring or signature comment.",
+        (
+            f"Public callables in `{record.module_name}` rendered from the "
+            "running interpreter at docs-build time. Drift between this "
+            "block and the prose elsewhere on the page indicates a stale "
+            "docstring or signature comment."
+        ),
         "",
     ]
     for name, sig in pairs:
@@ -1693,9 +1699,11 @@ def _kitchen_sink_markdown(package_name: str) -> str:
 
     # Body-only: stub supplies anchor + H1 so Sphinx finds a page title.
     lines = [
-        "Every directive and role this package registers, exercised once "
-        "on the same page — useful as a reference card for downstream "
-        "authors and as a visual-regression target.",
+        (
+            "Every directive and role this package registers, exercised once "
+            "on the same page — useful as a reference card for downstream "
+            "authors and as a visual-regression target."
+        ),
         "",
     ]
     if directives_seen:
@@ -1815,9 +1823,11 @@ def _surface_changelog_markdown(package_name: str) -> str:
 
     # Body-only: stub supplies anchor + H1 so Sphinx finds a page title.
     lines = [
-        "Comparison of the package's currently-registered directives, "
-        "roles, and config values against the snapshot stored at "
-        f"`docs/_static/surface-snapshots/{package_name}.json`.",
+        (
+            "Comparison of the package's currently-registered directives, "
+            "roles, and config values against the snapshot stored at "
+            f"`docs/_static/surface-snapshots/{package_name}.json`."
+        ),
         "",
     ]
     if not snapshot_path.is_file():
@@ -1928,8 +1938,10 @@ def _package_dependents_markdown(package_name: str) -> str:
     dependents = _package_dependents(package_name)
     # Body-only: stub supplies anchor + H1 so Sphinx finds a page title.
     lines = [
-        f"Workspace packages that declare a `{package_name}` dependency in "
-        "their `pyproject.toml` `[project].dependencies` array.",
+        (
+            f"Workspace packages that declare a `{package_name}` dependency in "
+            "their `pyproject.toml` `[project].dependencies` array."
+        ),
         "",
     ]
     if not dependents:

docs/_ext/sphinx_demo_builder.py

@@ -21,7 +21,7 @@
 from sphinx.roles import XRefRole
 
 if t.TYPE_CHECKING:
-    from collections.abc import Iterator, Set
+    from collections.abc import Iterator, Set as AbstractSet
 
     from docutils import nodes
     from sphinx.application import Sphinx
@@ -49,7 +49,7 @@ def get_target_uri(self, docname: str, typ: str | None = None) -> str:
         """Return the in-archive URI for a document."""
         return f"{docname}.txt"
 
-    def prepare_writing(self, docnames: Set[str]) -> None:
+    def prepare_writing(self, docnames: AbstractSet[str]) -> None:
         """No writer state is needed for the demo."""
 
     def write_doc(self, docname: str, doctree: nodes.document) -> None:

docs/packages/sphinx-vite-builder/how-to.md

@@ -33,7 +33,7 @@ SIGKILL teardown on signal / `atexit`.
 ```python
 # docs/conf.py
 extensions = ["sphinx_vite_builder"]
-sphinx_vite_builder_mode = "auto"        # "auto" | "dev" | "prod"
+sphinx_vite_builder_mode = "auto"  # "auto" | "dev" | "prod"
 sphinx_vite_builder_root = "/abs/path/to/web"
 ```
 

docs/quickstart.md

@@ -62,6 +62,7 @@ In your project's `docs/conf.py`:
 
 ```python
 """Sphinx configuration for my-project."""
+
 from __future__ import annotations
 
 from gp_sphinx.config import merge_sphinx_config
@@ -145,6 +146,7 @@ Create a file `my_module.py` next to your `docs/` directory:
 
 ```python
 """Demo module for the autodoc design system."""
+
 from __future__ import annotations
 
 from typing import Any

packages/gp-sphinx/README.md

@@ -20,6 +20,7 @@ Replace ~300 lines of duplicated `docs/conf.py` with ~10 lines:
 
 ```python
 """Sphinx configuration for my-project."""
+
 from __future__ import annotations
 
 from gp_sphinx.config import merge_sphinx_config

packages/sphinx-autodoc-argparse/src/sphinx_autodoc_argparse/domain.py

@@ -34,7 +34,7 @@
 from sphinx.util.nodes import make_refnode
 
 if t.TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator, Set
+    from collections.abc import Iterable, Iterator, Set as AbstractSet
 
     from docutils import nodes
     from docutils.nodes import Element
@@ -299,7 +299,7 @@ def clear_doc(self, docname: str) -> None:
 
     def merge_domaindata(
         self,
-        docnames: Set[str],
+        docnames: AbstractSet[str],
         otherdata: dict[str, t.Any],
     ) -> None:
         """Merge sibling worker's ``domaindata`` under parallel builds."""

packages/sphinx-autodoc-docutils/src/sphinx_autodoc_docutils/domain.py

@@ -36,7 +36,7 @@
 from sphinx.util.nodes import make_id, make_refnode
 
 if t.TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator, Set
+    from collections.abc import Iterable, Iterator, Set as AbstractSet
 
     from docutils import nodes
     from docutils.nodes import Element
@@ -303,7 +303,7 @@ def clear_doc(self, docname: str) -> None:
 
     def merge_domaindata(
         self,
-        docnames: Set[str],
+        docnames: AbstractSet[str],
         otherdata: dict[str, t.Any],
     ) -> None:
         """Merge sibling worker's ``domaindata`` under parallel builds."""

packages/sphinx-autodoc-fastmcp/README.md

@@ -33,7 +33,11 @@ fastmcp_area_map = {
 }
 fastmcp_model_module = "myproject.models"
 fastmcp_model_classes = {"SessionInfo", "WindowInfo"}
-fastmcp_section_badge_map = {"Inspect": "readonly", "Act": "mutating", "Destroy": "destructive"}
+fastmcp_section_badge_map = {
+    "Inspect": "readonly",
+    "Act": "mutating",
+    "Destroy": "destructive",
+}
 fastmcp_section_badge_pages = {"tools/index", "index"}
 fastmcp_collector_mode = "register"  # or "introspect"
 ```

packages/sphinx-autodoc-pytest-fixtures/src/sphinx_autodoc_pytest_fixtures/_transforms.py

@@ -22,8 +22,6 @@
     from sphinx.application import Sphinx
     from sphinx.domains.python import PythonDomain
 
-    pass
-
 logger = sphinx_logging.getLogger(__name__)
 
 _PARAMETER_FIELD_LABELS = frozenset(

packages/sphinx-autodoc-sphinx/src/sphinx_autodoc_sphinx/domain.py

@@ -36,7 +36,7 @@
 from sphinx.util.nodes import make_id, make_refnode
 
 if t.TYPE_CHECKING:
-    from collections.abc import Iterable, Iterator, Set
+    from collections.abc import Iterable, Iterator, Set as AbstractSet
 
     from docutils import nodes
     from docutils.nodes import Element
@@ -268,7 +268,7 @@ def clear_doc(self, docname: str) -> None:
 
     def merge_domaindata(
         self,
-        docnames: Set[str],
+        docnames: AbstractSet[str],
         otherdata: dict[str, t.Any],
     ) -> None:
         """Merge sibling worker's ``domaindata`` under parallel builds."""

packages/sphinx-autodoc-typehints-gp/src/sphinx_autodoc_typehints_gp/_field_xref_transform.py

@@ -274,7 +274,7 @@ def _is_em_dash_separator(text: str) -> bool:
     False
     """
     stripped = text.lstrip()
-    return stripped.startswith(_EN_DASH + " ") or stripped.startswith("-- ")
+    return stripped.startswith((_EN_DASH + " ", "-- "))
 
 
 _PROSE_FIELD_TOKENS: t.Final = (

packages/sphinx-gp-opengraph/src/sphinx_gp_opengraph/_description.py

@@ -26,13 +26,13 @@
 from docutils import nodes
 
 if t.TYPE_CHECKING:
-    from collections.abc import Set
+    from collections.abc import Set as AbstractSet
 
 
 def get_description(
     doctree: nodes.document,
     description_length: int,
-    known_titles: Set[str] = frozenset(),
+    known_titles: AbstractSet[str] = frozenset(),
 ) -> str:
     """Return a plain-text description extracted from ``doctree``.
 
@@ -83,7 +83,7 @@ def __init__(
         document: nodes.document,
         *,
         desc_len: int,
-        known_titles: Set[str] = frozenset(),
+        known_titles: AbstractSet[str] = frozenset(),
     ) -> None:
         super().__init__(document)
         self.description = ""

packages/sphinx-ux-badges/README.md

@@ -27,13 +27,15 @@ Then build badges in your directives or transforms:
 ```python
 from sphinx_ux_badges import build_badge, build_badge_group, build_toolbar
 
-group = build_badge_group([
-    build_badge(
-        "readonly",
-        tooltip="Read-only",
-        classes=["gp-sphinx-fastmcp__safety-readonly"],
-    ),
-])
+group = build_badge_group(
+    [
+        build_badge(
+            "readonly",
+            tooltip="Read-only",
+            classes=["gp-sphinx-fastmcp__safety-readonly"],
+        ),
+    ]
+)
 ```
 
 ## Documentation

packages/sphinx-vite-builder/README.md

@@ -156,7 +156,7 @@ during `sphinx-build` (one-shot) and `sphinx-autobuild` (watched).
 ```python
 # docs/conf.py
 extensions = ["sphinx_vite_builder"]
-sphinx_vite_builder_mode = "auto"        # "auto" | "dev" | "prod"
+sphinx_vite_builder_mode = "auto"  # "auto" | "dev" | "prod"
 sphinx_vite_builder_root = "/abs/path/to/web"
 ```
 

packages/sphinx-vite-builder/src/sphinx_vite_builder/_internal/process.py

@@ -38,9 +38,6 @@
 import sys
 import typing as t
 
-if t.TYPE_CHECKING:
-    pass
-
 _module_logger = logging.getLogger(__name__)
 
 

packages/sphinx-vite-builder/src/sphinx_vite_builder/_internal/vite.py

@@ -22,7 +22,6 @@
 import pathlib
 import shutil
 import textwrap
-import typing as t
 
 from .bus import AsyncioBus
 from .errors import (
@@ -395,9 +394,3 @@ def run_vite_build(
     "vite_build_command",
     "vite_watch_command",
 )
-
-
-# Re-exports for type-checker friendliness when consumers import
-# the orchestration module directly.
-_AsyncProcess: t.TypeAlias = AsyncProcess
-_AsyncioBus: t.TypeAlias = AsyncioBus