skills/mims-harvard__tooluniverse

Fork 0

mirror of https://github.com/mims-harvard/ToolUniverse.git synced 2026-09-19 07:31:47 +08:00

Files

T

Shanghua 1abee3938c clean docs

2026-02-23 12:38:53 -05:00

9.6 KiB

Raw Permalink Blame History

Documentation Standards

This guide establishes standards for ToolUniverse documentation to ensure consistency, maintainability, and quality.

Auto-Generated vs Manual Content

Auto-Generated Files

The following files are AUTO-GENERATED and should NOT be edited manually:

API Documentation

docs/api/tooluniverse.*.rst (except tooluniverse.rst - manual)
Generated by: sphinx-apidoc in CI/CD pipeline and docs/quick_doc_build.sh
Source: Python docstrings in src/tooluniverse/

Tool Documentation

docs/tools/*_tools.rst
Generated by: docs/generate_config_index.py, docs/generate_tool_reference.py
Source: JSON tool configurations in src/tooluniverse/data/

Identifying Auto-Generated Files

All auto-generated files MUST have this header:

.. AUTO-GENERATED - DO NOT EDIT MANUALLY
.. Generated by: docs/generate_config_index.py
.. Last updated: 2024-02-05

Editing Auto-Generated Content

To modify auto-generated documentation:

Edit source data:

For API docs: Update Python docstrings in src/tooluniverse/
For tool docs: Update JSON configs in src/tooluniverse/data/

Regenerate documentation:

cd docs
# For tool documentation
python generate_config_index.py
python generate_tool_reference.py

# For API documentation
sphinx-apidoc -f -o api ../src/tooluniverse

Commit both:

Commit source changes (docstrings or JSON)
Commit generated documentation
CI/CD will verify consistency

Manual Documentation

All other .rst and .md files are manually maintained:

User guides (docs/guide/)
Tutorials (docs/tutorials/)
Getting started (docs/quickstart.rst, docs/getting_started.rst)
Reference documentation (docs/reference/)
FAQ and troubleshooting (docs/help/, docs/faq.rst)

Configuration Reference Standards

Tool Counts

Standard: Use 1000+ tools consistently across documentation.

Actual count (as of latest): 1962 tools
Use rounded public-facing number for simplicity
Update only when crossing major milestones (e.g., 1500+ tools)

Where to update:

docs/index.rst - Main landing page
docs/quickstart.rst - Quick start guide
docs/guide/mcp_support.rst - MCP integration guide
README.md - GitHub README

Command-Line Interface

Standard: Always use CLI commands, not module invocations.

Correct:

tooluniverse-smcp
tooluniverse-smcp-stdio
tooluniverse-doctor

Incorrect:

python -m tooluniverse.smcp_server
python -m tooluniverse.doctor

Rationale: CLI commands are:

Shorter and easier to remember
Platform-independent
Official entry points defined in pyproject.toml

MCP Configuration

Standard: Use consistent MCP server settings.

Default Settings

Setting	Default Value	Purpose
Port	8000	HTTP server port
Timeout	600 (10 min)	Server startup timeout
Compact Mode	Recommended	Reduce context window usage
Transport	stdio	For desktop apps (Claude Desktop, Cursor)
Transport	HTTP/SSE	For web integrations

Configuration Template

STDIO (Desktop Apps):

{
 "mcpServers": {
   "tooluniverse": {
     "command": "tooluniverse-smcp-stdio",
     "args": ["--compact-mode"],
     "timeout": 600
   }
 }
}

HTTP (Web Integrations):

tooluniverse-smcp --port 8000 --compact-mode

Reusable MCP Snippets

Use includes from docs/_templates/mcp_config_snippets.rst for consistency:

.. include:: ../_templates/mcp_config_snippets.rst
  :start-after: .. _mcp-basic-config:
  :end-before: .. _mcp-custom-port:

File Organization

Directory Structure

docs/
├── index.rst                    # Main landing page
├── quickstart.rst              # 5-minute quick start
├── getting_started.rst         # Detailed tutorial
├── installation.rst            # Installation guide
├── api_keys.rst               # API key configuration
├── faq.rst                    # Quick FAQ (brief answers)
├── glossary.rst               # Technical term definitions
├── reference/                 # Reference documentation
│   ├── cli_tools.rst         # CLI tools reference
│   ├── environment_variables.rst  # Environment variables
│   └── data_sources.rst      # Data source catalog
├── guide/                     # User guides
│   ├── mcp_support.rst       # MCP integration
│   ├── loading_tools.rst     # Tool loading
│   ├── cache_system.rst      # Caching guide
│   └── ...
├── help/                      # Help resources
│   ├── faq.rst               # Comprehensive FAQ
│   └── troubleshooting.rst   # Troubleshooting guide
├── tutorials/                 # Step-by-step tutorials
├── api/                       # Auto-generated API docs
├── tools/                     # Auto-generated tool docs
└── _templates/                # Reusable snippets
   └── mcp_config_snippets.rst

Clear learning path (no circular references):

Start Here section on index.rst
Quickstart (quickstart.rst) - 5 minutes
Getting Started (getting_started.rst) - 30 minutes
Guides (guide/) - Deep dives
Reference (reference/) - Lookup documentation

Avoid:

Quickstart → Getting Started → Quickstart (circular)
"You should have completed X first" (unless truly required)

Content Quality Standards

"Why" Sections

Major features MUST include "Why" section explaining:

Problem: What problem does this solve?
Solution: How does this feature help?
Use cases: When to use vs when to skip?

Examples:

docs/guide/mcp_support.rst - "Why Use MCP?"
docs/guide/compact_mode.rst - "Why Use Compact Mode?"
docs/guide/cache_system.rst - "Why Use Caching?"

Jargon Definitions

Technical terms MUST be defined on first use:

A :term:`tool specification <Tool Specification>` is like an instruction 
manual for each tool - it describes what inputs it needs and what outputs 
it produces.

Add terms to docs/glossary.rst for reference.

Code Examples

Realistic Examples

Use real data in examples:

Good:

# Real UniProt accession for amyloid precursor protein
result = tu.run({
   "name": "UniProt_get_entry_by_accession",
   "arguments": {"accession": "P05067"}
})

Bad:

# Placeholder - unhelpful
result = tu.run({
   "name": "SomeTool",
   "arguments": {"id": "XXXXX"}
})

Tested Examples

All code examples in documentation should be tested:

Add examples to examples/ directory
Run automated tests: pytest tests/examples/
Update documentation if APIs change

Error Documentation

Common errors MUST include:

Error code (e.g., 401, 429, 503)
Meaning (what the error indicates)
Solution (how to fix it)
Link to related docs

See docs/help/troubleshooting.rst for the error code reference table.

Build & CI/CD Standards

Documentation Generation

CI/CD MUST regenerate auto-generated docs:

# .github/workflows/deploy-docs.yml
- name: Regenerate tool documentation
 run: |
   cd docs
   python generate_config_index.py
   python generate_remote_tools_docs.py
   python generate_tool_reference.py

Validation

Pre-commit hooks SHOULD validate:

# .githooks/pre-commit-docs
python scripts/validate_documentation.py

Validates:

Broken internal links
Outdated tool counts
Deprecated commands
Missing auto-generated file headers

Caching Strategy

Do cache:

Sphinx doctrees (docs/_build/doctrees)

Don't cache:

API docs (docs/api/)
Tool docs (docs/tools/)

Rationale: Generated docs must reflect current source code.

Style Guide

Headings

Use consistent heading hierarchy:

Page Title
==========

Major Section
-------------

Subsection
~~~~~~~~~~

Sub-subsection
^^^^^^^^^^^^^^

Lists

Use checklists for actionable items:

✅ Do this
✅ Also do this
❌ Don't do this

Admonitions

Use appropriate admonition types:

.. note::
  Informational content

.. tip::
  Helpful suggestions

.. warning::
  Caution about potential issues

.. important::
  Critical information

.. seealso::
  Related content links

Cross-References

Always use Sphinx cross-references, not hardcoded links: