mims-harvard__tooluniverse/docs/dev_docs/DOCUMENTATION_STANDARDS.md

# 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:

```rst
.. 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:

1. **Edit source data**:
  - For API docs: Update Python docstrings in `src/tooluniverse/`
  - For tool docs: Update JSON configs in `src/tooluniverse/data/`

2. **Regenerate documentation**:
  ```bash
  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
  ```

3. **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**:
```bash
tooluniverse-smcp
tooluniverse-smcp-stdio
tooluniverse-doctor
```

Incorrect:
```bash
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)**:
```json
{
 "mcpServers": {
   "tooluniverse": {
     "command": "tooluniverse-smcp-stdio",
     "args": ["--compact-mode"],
     "timeout": 600
   }
 }
}
```

**HTTP (Web Integrations)**:
```bash
tooluniverse-smcp --port 8000 --compact-mode
```

### Reusable MCP Snippets

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

```rst
.. 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
```

### Navigation Hierarchy

**Clear learning path** (no circular references):

1. **Start Here** section on `index.rst`
2. **Quickstart** (`quickstart.rst`) - 5 minutes
3. **Getting Started** (`getting_started.rst`) - 30 minutes
4. **Guides** (`guide/`) - Deep dives
5. **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:

```rst
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**:
```python
# Real UniProt accession for amyloid precursor protein
result = tu.run({
   "name": "UniProt_get_entry_by_accession",
   "arguments": {"accession": "P05067"}
})
```

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

#### Tested Examples

**All code examples** in documentation should be tested:

1. Add examples to `examples/` directory
2. Run automated tests: `pytest tests/examples/`
3. Update documentation if APIs change

### Error Documentation

Common errors **MUST** include:

1. **Error code** (e.g., 401, 429, 503)
2. **Meaning** (what the error indicates)
3. **Solution** (how to fix it)
4. **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:

```yaml
# .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:

```bash
# .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:

```rst
Page Title
==========

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

Subsection
~~~~~~~~~~

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

### Lists

**Use checklists** for actionable items:

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

### Admonitions

Use appropriate admonition types:

```rst
.. 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:

**Good**:
```rst
See :doc:`installation` for setup instructions.
See :ref:`mcp-basic-config` for configuration.
```

**Bad**:
```rst
See [installation.html](installation.html) for setup.
```

## Maintenance Workflow

### Quarterly Review

Every 3 months:

1.  Run validation scripts
2.  Check for outdated content
3.  Update tool counts if needed
4.  Review navigation flow
5.  Test all code examples
6.  Update "What's New" section

### When to Update

**Update immediately**:
- Breaking API changes
- New major features
- Critical bug fix documentation
- Security-related changes

**Update in batch**:
- Minor tool additions
- Small clarifications
- Typo fixes
- Internal link updates

### Version Control

-  Commit documentation with related code changes
-  Use descriptive commit messages: "docs: add CLI tools reference"
-  Include "Closes #123" for issue-related docs
-  Don't commit without testing locally first

## Contact & Questions

For questions about documentation standards:

1. Check existing documentation
2. Review this standards guide
3. Open GitHub issue with `[docs]` tag
4. Discuss in Slack community

---

**Last updated**: 2026-02-05  
**Maintained by**: ToolUniverse Documentation Team