Shanghua Gao 13d6bc073f Fix Sphinx docs drift on the two highest-traffic new-user pages (#365) ...

Docs-vs-code angle on the "declared vs runtime reality" audit, prioritizing
the pages a new user hits first: docs/index.rst's "Get Started" section
links to exactly 3 pages (guide/building_ai_scientists/index -> claude_code,
guide/tu_cli, guide/python_guide). Checked all three plus a full-tree
:doc: cross-reference audit before touching anything.

Full-tree check (clean, no fix needed): wrote a resolver for every :doc:
role in the docs tree (1391 references across all .rst files, correctly
handling Sphinx's relative-to-current-file resolution) -- zero broken.
One reference I suspected was broken (bare `mcp_support` in claude_code.rst)
turned out correct once I checked it resolves relative to its own file's
directory, not the referencing page I'd conflated it with. Good reminder
to trust the resolver over my own path arithmetic.

tu_cli.rst: read fully, live-ran every example command (list/grep/find/
info/run/test/status/build/serve, including the two not yet covered by
prior rounds: `tu test Dryad_search_datasets`, `tu run list_tools
'{"mode": "categories"}'`, `tu info ... ChEMBL_get_molecule`) -- all
correct, this page was already accurate (its `tu build` description
already covered both side effects found in PR #361, independently of that
fix).

Real bugs found and fixed, both live-verified before and after:

- docs/guide/python_guide.rst -- Quick Start / Tool Loading Options used
  `tu.load_tools(tool_type=[...])` twice. `tool_type` is a real parameter
  but load_tools()'s own docstring says "Deprecated alias for categories"
  -- confirmed live: it works but emits `DeprecationWarning:
  load_tools(tool_type=...) is deprecated; use categories= instead` on a
  brand-new user's first Quick Start run. Changed both to `categories=`.
  Also: the Literature Search example calls `PubTator_search_publications`,
  which does not exist in the registry at all -- confirmed via a full
  ToolUniverse().load_tools() name-set lookup. Found the real tool
  (PubTator3_LiteratureSearch, same query/limit params) by checking
  pubtator3_ext_tools.json, confirmed its exact param signature and
  live-ran it successfully before swapping the name in.
- docs/guide/building_ai_scientists/claude_code.rst -- the primary Claude
  Code plugin install page (linked directly from the homepage) had the
  same two gaps already found and fixed elsewhere this thread but never
  ported to this independent file: (1) "What you get" table missing 3 of
  8 slash commands (verify-references, self-review, setup-keys) -- same
  gap as the skill doc fixed in an earlier round; (2) zero mention of
  enabling plugin auto-update (PR #285/#358) -- added the same guidance,
  plus a note in "Update / uninstall" that it's unnecessary once enabled.

Verified the rest of both files against live source before ruling them
clean: tool_specification()'s return shape, list_built_in_tools(mode=...),
the Tool_Finder_* tool names and their `description`/`limit` params, the
direct-import calling convention, docs/.env.template's existence, and the
hooks/index doc target -- all matched.

Validated both edited files with a real Sphinx dummy-build (not just bare
docutils, which doesn't know the project's own directives like tab-set/
card/grid/dropdown and reports false-positive noise on every such
directive) -- zero warnings or errors on either file. The build's ~150
pre-existing warnings (ghost_tool/medrxiv_tool import failures, autodoc
docstring formatting) are all unrelated, matching known pre-existing
noise already documented from an earlier docs cleanup round.

2026-07-21 02:34:45 -04:00

12 KiB

Raw Permalink Blame History

View Raw