feat(docs[_ext]): Make safety badges accessible and non-selectable

why: Badges should be screen-reader friendly (WCAG) and not pollute
text when users copy tool names.
what:
- CSS: user-select: none on .sd-badge (prevents copy-selection)
- Custom _safety_badge_node with HTML visitor that emits role="note"
  and aria-label="Safety tier: <tier>" on every badge span
- Screen readers announce "Safety tier: readonly" etc. for context
- Badge text stays in DOM (visible, not pseudo-element)
- Add test for ARIA attribute storage on badge nodes

Author: tony

docs/_ext/fastmcp_autodoc.py

@@ -421,15 +421,38 @@ def _extract_enum_values(type_str: str) -> list[str]:
     return values
 
 
-def _safety_badge(safety: str) -> nodes.inline:
-    """Create a colored safety badge node."""
+class _safety_badge_node(nodes.General, nodes.Inline, nodes.Element):
+    """Custom node for safety badges with ARIA attributes in HTML output."""
+
+
+def _visit_safety_badge_html(self: t.Any, node: _safety_badge_node) -> None:
+    """Emit opening ``<span>`` with classes, role, and aria-label."""
+    classes = " ".join(node.get("classes", []))
+    safety = node.get("safety", "")
+    self.body.append(
+        f'<span class="{classes}" role="note" aria-label="Safety tier: {safety}">'
+    )
+
+
+def _depart_safety_badge_html(self: t.Any, node: _safety_badge_node) -> None:
+    """Close the ``<span>``."""
+    self.body.append("</span>")
+
+
+def _safety_badge(safety: str) -> _safety_badge_node:
+    """Create a colored safety badge node with ARIA attributes."""
     _base = ["sd-sphinx-override", "sd-badge"]
     classes = {
         "readonly": [*_base, "sd-bg-success", "sd-bg-text-success"],
         "mutating": [*_base, "sd-bg-warning", "sd-bg-text-warning"],
         "destructive": [*_base, "sd-bg-danger", "sd-bg-text-danger"],
     }
-    badge = nodes.inline("", safety, classes=classes.get(safety, []))
+    badge = _safety_badge_node(
+        "",
+        nodes.Text(safety),
+        classes=classes.get(safety, []),
+        safety=safety,
+    )
     return badge
 
 
@@ -926,6 +949,10 @@ def _badge_role(
 
 def setup(app: Sphinx) -> ExtensionMetadata:
     """Register the fastmcp_autodoc extension."""
+    app.add_node(
+        _safety_badge_node,
+        html=(_visit_safety_badge_html, _depart_safety_badge_html),
+    )
     app.connect("builder-inited", _collect_tools)
     app.connect("doctree-read", _register_tool_labels)
     app.connect("doctree-resolved", _add_section_badges)

docs/_static/css/custom.css

@@ -245,6 +245,8 @@ img[src*="codecov.io"] {
 .sd-badge {
   font-size: 0.75rem;
   vertical-align: middle;
+  user-select: none;        /* Don't include badge text when copying */
+  -webkit-user-select: none; /* Safari */
 }
 
 .sd-badge.sd-bg-warning {

tests/docs/_ext/test_fastmcp_autodoc.py

@@ -432,7 +432,7 @@ def test_make_type_cell_single_type() -> None:
 
 
 def test_safety_badge_classes() -> None:
-    """_safety_badge creates inline nodes with correct CSS classes."""
+    """_safety_badge creates badge nodes with correct CSS classes."""
     badge = fastmcp_autodoc._safety_badge("readonly")
     assert "sd-bg-success" in badge["classes"]
 
@@ -443,6 +443,16 @@ def test_safety_badge_classes() -> None:
     assert "sd-bg-danger" in badge["classes"]
 
 
+def test_safety_badge_aria_attributes() -> None:
+    """_safety_badge stores safety tier for ARIA output."""
+    badge = fastmcp_autodoc._safety_badge("readonly")
+    assert badge["safety"] == "readonly"
+    assert badge.astext() == "readonly"
+
+    badge = fastmcp_autodoc._safety_badge("destructive")
+    assert badge["safety"] == "destructive"
+
+
 # ---------------------------------------------------------------------------
 # _make_type_xref
 # ---------------------------------------------------------------------------
@@ -531,15 +541,13 @@ def _make_doc_with_section(
 
 def test_add_section_badges_appends_badge_on_tools_index() -> None:
     """_add_section_badges appends badge when fromdocname is tools/index."""
-    from docutils import nodes
-
     doc, _section, title = _make_doc_with_section("inspect", "Inspect")
 
     fastmcp_autodoc._add_section_badges(None, doc, "tools/index")
 
     assert len(title.children) == 3
     badge = title.children[2]
-    assert isinstance(badge, nodes.inline)
+    assert isinstance(badge, fastmcp_autodoc._safety_badge_node)
     assert "sd-bg-success" in badge["classes"]
     assert badge.astext() == "readonly"
 
@@ -585,7 +593,7 @@ def test_add_section_badges_parenthesized_on_index() -> None:
     assert len(title.children) == 2
     assert title.children[0].astext() == "Inspect "
     badge = title.children[1]
-    assert isinstance(badge, nodes.inline)
+    assert isinstance(badge, fastmcp_autodoc._safety_badge_node)
     assert "sd-bg-success" in badge["classes"]
     assert badge.astext() == "readonly"
 
@@ -598,7 +606,7 @@ def test_add_section_badges_works_on_homepage() -> None:
 
     assert len(title.children) == 3
     badge = title.children[2]
-    assert isinstance(badge, nodes.inline)
+    assert isinstance(badge, fastmcp_autodoc._safety_badge_node)
     assert "sd-bg-warning" in badge["classes"]