fix(docs[_ext]): Pin badge size in headings, scope to tools index only

why: Badges in h2 headings inherited the heading font size, making them
oversized. Section badges on individual tool pages were redundant since
every tool already has its own badge.
what:
- CSS: Pin .sd-badge to 0.75rem with vertical-align: middle
- Scope _add_section_badges to fromdocname == "tools/index" only
- Add test for page scoping (tools/sessions skipped)
- Refactor test helper to reduce duplication

Author: tony

docs/_ext/fastmcp_autodoc.py

@@ -752,9 +752,14 @@ def _add_section_badges(
 ) -> None:
     """Append safety badges to Inspect/Act/Destroy section headings.
 
+    Only applied to the tools index page — individual tool pages already
+    have per-tool badges, making section-level badges redundant.
+
     Runs at ``doctree-resolved`` — section IDs are already frozen, so
     appending nodes to the title doesn't affect anchors or cross-refs.
     """
+    if fromdocname != "tools/index":
+        return
     for section in doctree.findall(nodes.section):
         if not section.children or not isinstance(section[0], nodes.title):
             continue

docs/_static/css/custom.css

@@ -234,6 +234,11 @@ img[src*="codecov.io"] {
 }
 
 /* ── MCP Tool safety badges ──────────────────────────────
- * Badge sits inline next to the tool name in the heading.
- * Slight vertical offset for alignment with the code text.
+ * Badges appear inline in both h2/h3 headings and body text.
+ * Pin size to body-text scale so they don't inflate in headings.
+ * Vertical-align keeps them centered with adjacent text.
  * ────────────────────────────────────────────────────────── */
+.sd-badge {
+  font-size: 0.75rem;
+  vertical-align: middle;
+}

tests/docs/_ext/test_fastmcp_autodoc.py

@@ -6,6 +6,7 @@
 
 import fastmcp_autodoc
 import pytest
+from docutils import nodes
 
 # ---------------------------------------------------------------------------
 # _parse_numpy_params
@@ -455,25 +456,31 @@ def test_section_badge_map_headings() -> None:
     assert m["Destroy"] == "destructive"
 
 
-def test_add_section_badges_appends_badge_to_title() -> None:
-    """_add_section_badges appends a safety badge to matching titles."""
+def _make_doc_with_section(
+    section_id: str, title_text: str
+) -> tuple[nodes.document, nodes.section, nodes.title]:
+    """Build a minimal doctree with one section."""
     from docutils import nodes
     from docutils.frontend import OptionParser
     from docutils.utils import new_document
 
     settings = OptionParser(components=()).get_default_values()
     doc = new_document("test", settings)
-
-    section = nodes.section(ids=["inspect"])
-    title = nodes.title("", "Inspect")
+    section = nodes.section(ids=[section_id])
+    title = nodes.title("", title_text)
     section += title
     doc += section
+    return doc, section, title
+
+
+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
 
-    # Simulate the handler — it expects (app, doctree, fromdocname)
-    # but only uses doctree, so pass None for the others.
-    fastmcp_autodoc._add_section_badges(None, doc, "")
+    doc, _section, title = _make_doc_with_section("inspect", "Inspect")
+
+    fastmcp_autodoc._add_section_badges(None, doc, "tools/index")
 
-    # Title should now have 3 children: Text("Inspect"), Text(" "), inline(badge)
     assert len(title.children) == 3
     badge = title.children[2]
     assert isinstance(badge, nodes.inline)
@@ -483,39 +490,29 @@ def test_add_section_badges_appends_badge_to_title() -> None:
 
 def test_add_section_badges_preserves_section_id() -> None:
     """_add_section_badges does not change the section ID."""
-    from docutils import nodes
-    from docutils.frontend import OptionParser
-    from docutils.utils import new_document
+    doc, section, _title = _make_doc_with_section("inspect", "Inspect")
 
-    settings = OptionParser(components=()).get_default_values()
-    doc = new_document("test", settings)
+    fastmcp_autodoc._add_section_badges(None, doc, "tools/index")
 
-    section = nodes.section(ids=["inspect"])
-    section += nodes.title("", "Inspect")
-    doc += section
+    assert section["ids"] == ["inspect"]
 
-    fastmcp_autodoc._add_section_badges(None, doc, "")
 
-    assert section["ids"] == ["inspect"]
+def test_add_section_badges_skips_non_index_pages() -> None:
+    """_add_section_badges skips individual tool pages (redundant)."""
+    doc, _section, title = _make_doc_with_section("inspect", "Inspect")
 
+    fastmcp_autodoc._add_section_badges(None, doc, "tools/sessions")
 
-def test_add_section_badges_ignores_non_matching() -> None:
-    """_add_section_badges leaves non-matching headings untouched."""
-    from docutils import nodes
-    from docutils.frontend import OptionParser
-    from docutils.utils import new_document
+    assert len(title.children) == 1
+    assert title.astext() == "Inspect"
 
-    settings = OptionParser(components=()).get_default_values()
-    doc = new_document("test", settings)
 
-    section = nodes.section(ids=["overview"])
-    title = nodes.title("", "Overview")
-    section += title
-    doc += section
+def test_add_section_badges_ignores_non_matching() -> None:
+    """_add_section_badges leaves non-matching headings untouched."""
+    doc, _section, title = _make_doc_with_section("overview", "Overview")
 
-    fastmcp_autodoc._add_section_badges(None, doc, "")
+    fastmcp_autodoc._add_section_badges(None, doc, "tools/index")
 
-    # Title should still have only the original text child
     assert len(title.children) == 1
     assert title.astext() == "Overview"