docs(refactor[package-reference]): drop docutils role monkey-patch

why: The `collect_extension_surface()` and `_seed_python_objects_map()`
helpers each monkey-patched
`docutils.parsers.rst.roles.register_local_role` /
`register_canonical_role` so that `sphinx-autodoc-argparse`'s
`register_roles()` — which registered its five `cli-*` roles via the
docutils global — would be discoverable by the RecorderApp. Now that
argparse registers via `Sphinx.add_role`, the RecorderApp captures
those calls through its own `__getattr__`, and the monkey-patch has
nothing left to catch. Removing it drops three `t.cast("t.Any", …)`
casts, two try/finally blocks that mutated process-global docutils
state, and an entire `"docutils role"` post-processing branch.
what:
- Delete the `registered_roles` / `_record_local` / role-patch
  try-finally in `collect_extension_surface()` (lines 317–336) and
  the trailing "docutils role" emission loop (lines 443–451)
- Delete the `docutils_roles` / `_capture` / role-patch try-finally
  in `_seed_python_objects_map()` and the trailing
  `docutils_roles`-based `raw_objs` append (lines 781–823)
- Drop the `from docutils.parsers.rst import roles` import (no other
  references remain in this file)
- Update the module-level architecture docstring to describe the
  `RecorderApp.__getattr__` approach instead of the removed
  monkey-patch
- Verified via `just build-docs`: the argparse package reference
  page still lists all five `cli-*` roles (27 occurrences in the
  rendered HTML, captured through the "add_role" branch)

Author: tony

docs/_ext/package_reference.py

@@ -11,10 +11,10 @@
    its name, version, description, classifiers, and GitHub URL.
 
 2. **Surface extraction** (``collect_extension_surface()``) — imports the
-   module and monkey-patches ``app.add_*`` methods on a lightweight mock
-   ``Sphinx`` object to intercept calls that ``setup()`` makes.  Each
-   registered item (config value, directive, role, lexer, theme) is captured
-   into a ``SurfaceDict``.
+   module and passes a lightweight ``RecorderApp`` to its ``setup()``.
+   ``RecorderApp.__getattr__`` captures every ``app.add_*`` call so each
+   registered item (config value, directive, role, lexer, theme) flows
+   into a ``SurfaceDict`` without monkey-patching docutils globals.
 
 3. **Rendering** (``package_reference_markdown()``) — converts the collected
    surface into a Markdown fragment (config snippet + tables), which the
@@ -64,7 +64,6 @@
 import sys
 import typing as t
 
-from docutils.parsers.rst import roles
 from sphinx.util.docutils import SphinxDirective
 
 if t.TYPE_CHECKING:
@@ -314,26 +313,8 @@ def collect_extension_surface(module_name: str) -> SurfaceDict:
             themes=[],
         )
     app = RecorderApp()
-    registered_roles: list[tuple[str, object]] = []
-    original_local = roles.register_local_role
-    original_canonical = roles.register_canonical_role
-
-    def _record_local(name: str, role: object) -> None:
-        registered_roles.append((name, role))
-
-    # Temporarily replace the two docutils global role-registration functions so
-    # that any role registered by setup(app) is captured in registered_roles.
-    # The try/finally guarantees restoration even if setup() raises.
-    # Limitation: this mutates process-global state and is not safe for
-    # parallel Sphinx builds (sphinx -j N); single-threaded builds only.
-    try:
-        roles.register_local_role = t.cast("t.Any", _record_local)
-        roles.register_canonical_role = t.cast("t.Any", _record_local)
-        setup = t.cast("t.Callable[[object], object]", getattr(module, "setup"))
-        setup(app)
-    finally:
-        roles.register_local_role = original_local
-        roles.register_canonical_role = original_canonical
+    setup = t.cast("t.Callable[[object], object]", getattr(module, "setup"))
+    setup(app)
 
     config_values: list[dict[str, str]] = []
     directives: list[dict[str, str]] = []
@@ -440,16 +421,6 @@ def _record_local(name: str, role: object) -> None:
                 },
             )
 
-    for role_name, role_fn in registered_roles:
-        role_items.append(
-            {
-                "name": role_name,
-                "kind": "docutils role",
-                "callable": object_path(role_fn),
-                "summary": summarize(getattr(role_fn, "__doc__", None)),
-            },
-        )
-
     return {
         "module": module_name,
         "config_values": unique_by_name(config_values),
@@ -806,26 +777,10 @@ def _register_extension_objects(
                 continue
 
             recorder = RecorderApp()
-            docutils_roles: list[tuple[str, object]] = []
-            original_local = roles.register_local_role
-            original_canonical = roles.register_canonical_role
-
-            def _capture(
-                role_name: str,
-                role_fn: object,
-                _roles: list[tuple[str, object]] = docutils_roles,
-            ) -> None:
-                _roles.append((role_name, role_fn))
-
             try:
-                roles.register_local_role = t.cast("t.Any", _capture)
-                roles.register_canonical_role = t.cast("t.Any", _capture)
                 setup_fn(recorder)
             except Exception:
                 continue
-            finally:
-                roles.register_local_role = original_local
-                roles.register_canonical_role = original_canonical
 
             raw_objs: list[tuple[object, str]] = []  # (obj, objtype)
             for call_name, args, _kwargs in recorder.calls:
@@ -845,10 +800,6 @@ def _capture(
                     )
                 elif call_name == "add_lexer" and len(args) >= 2:
                     raw_objs.append((args[1], "class"))
-            for _role_name, role_fn in docutils_roles:
-                raw_objs.append(
-                    (role_fn, "function" if not inspect.isclass(role_fn) else "class"),
-                )
 
             for obj, objtype in raw_objs:
                 mod = getattr(obj, "__module__", None) or type(obj).__module__