sphinx-autodoc-argparse(refactor[typing]): register CLI roles via Sphinx.add_role

why: The five `cli-*` inline roles were registered via
`docutils.parsers.rst.roles.register_local_role`, which is typed
strictly for docutils-shaped callables and rejects Sphinx-style role
functions — each call needed `# type: ignore[arg-type]`.
`Sphinx.add_role(name: str, role: Any, override: bool = False)`
(`sphinx/application.py:1121`) accepts sphinx-shaped roles cleanly
and scopes registration to the Sphinx app rather than mutating
docutils process-global state.
what:
- Change `register_roles() -> None` to
  `register_roles(app: Sphinx) -> None`
- Replace 5 `roles.register_local_role(..., ...)  # type: ignore[arg-type]`
  calls with `app.add_role(...)` — removes 5 ignores
- Drop `from docutils.parsers.rst import roles` import
- Add `TYPE_CHECKING` import of `sphinx.application.Sphinx`
- Expand docstring to explain the scope change; convert the doctest
  to the standard `>>> register_roles  # doctest: +ELLIPSIS` form
  used elsewhere in the workspace
- Update the single caller in `exemplar.py:setup` to pass `app`
- Tighten `tests/ext/test_argparse_roles.py::test_register_roles`
  to verify the five expected role names are registered, using a
  local `_RoleRecorder` stub cast to `Sphinx`

Author: tony

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

@@ -1364,7 +1364,7 @@ def setup(app: Sphinx) -> SetupDict:
     # Register CLI inline roles for documentation
     from sphinx_autodoc_argparse.roles import register_roles
 
-    register_roles()
+    register_roles(app)
 
     return {
         "version": __version__,

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

@@ -16,10 +16,10 @@
 import typing as t
 
 from docutils import nodes
-from docutils.parsers.rst import roles
 
 if t.TYPE_CHECKING:
     from docutils.parsers.rst.states import Inliner
+    from sphinx.application import Sphinx
 
 
 def normalize_options(options: dict[str, t.Any] | None) -> dict[str, t.Any]:
@@ -348,8 +348,14 @@ def cli_choice_role(
     return [node], []
 
 
-def register_roles() -> None:
-    """Register all CLI roles with docutils.
+def register_roles(app: Sphinx) -> None:
+    """Register all CLI roles with the Sphinx application.
+
+    Uses :meth:`sphinx.application.Sphinx.add_role` (Sphinx-scoped)
+    rather than ``docutils.parsers.rst.roles.register_local_role``
+    (docutils process-global).  The Sphinx accessor is typed as
+    ``(name: str, role: Any, override: bool = False) -> None`` so no
+    ``# type: ignore`` is required.
 
     This function registers the following roles:
     - cli-option: For CLI options (--verbose, -h)
@@ -358,13 +364,19 @@ def register_roles() -> None:
     - cli-default: For default values (None, "default")
     - cli-choice: For choice values (json, yaml)
 
+    Parameters
+    ----------
+    app : Sphinx
+        The Sphinx application instance.  Must be called from within
+        an extension ``setup(app)`` hook.
+
     Examples
     --------
-    >>> register_roles()
-    >>> # Roles are now available in docutils RST parsing
+    >>> register_roles  # doctest: +ELLIPSIS
+    <function register_roles at 0x...>
     """
-    roles.register_local_role("cli-option", cli_option_role)  # type: ignore[arg-type]
-    roles.register_local_role("cli-metavar", cli_metavar_role)  # type: ignore[arg-type]
-    roles.register_local_role("cli-command", cli_command_role)  # type: ignore[arg-type]
-    roles.register_local_role("cli-default", cli_default_role)  # type: ignore[arg-type]
-    roles.register_local_role("cli-choice", cli_choice_role)  # type: ignore[arg-type]
+    app.add_role("cli-option", cli_option_role)
+    app.add_role("cli-metavar", cli_metavar_role)
+    app.add_role("cli-command", cli_command_role)
+    app.add_role("cli-default", cli_default_role)
+    app.add_role("cli-choice", cli_choice_role)

tests/ext/test_argparse_roles.py

@@ -17,6 +17,9 @@
     register_roles,
 )
 
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
 # --- normalize_options tests ---
 
 
@@ -311,9 +314,25 @@ def test_cli_choice_role(
 
 
 def test_register_roles() -> None:
-    """Test register_roles doesn't raise errors."""
-    # This should not raise any exceptions
-    register_roles()
+    """register_roles() registers the five CLI roles via app.add_role()."""
+
+    class _RoleRecorder:
+        def __init__(self) -> None:
+            self.added: list[tuple[str, object]] = []
+
+        def add_role(self, name: str, role: object, override: bool = False) -> None:
+            self.added.append((name, role))
+
+    app = _RoleRecorder()
+    register_roles(t.cast("Sphinx", app))
+
+    assert [name for name, _ in app.added] == [
+        "cli-option",
+        "cli-metavar",
+        "cli-command",
+        "cli-default",
+        "cli-choice",
+    ]
 
 
 # --- Role Return Type Tests ---