mims-harvard__tooluniverse/docs/dev_docs/UTILITY_SCRIPTS.md

Documentation Utility Scripts

This document provides a comprehensive guide to all utility scripts in the docs/ directory.

Quick Reference

Script	Purpose	When to Run	CI/CD
generate_config_index.py	Generate tool catalog pages	After tool config changes	Yes
generate_tool_reference.py	Generate tool reference docs	After tool config changes	Yes
generate_remote_tools_docs.py	Generate remote tool docs	After remote tool README changes	Yes
quick_doc_build.sh	Fast local documentation build	Before committing doc changes	No
quick_build_zh.sh	Fast Chinese docs build	Chinese localization work	No
validate_examples.py	Validate code examples	Before releases	Not yet
doc_analytics.py	Analyze documentation metrics	Documentation reviews	No
doc_sync_tool.py	Sync docstrings to docs	API doc updates	Not yet
validate_simple.py	(Empty file - unused)	N/A	No

---

Documentation Generation Scripts

generate_config_index.py

Purpose: Generates separate RST pages for each tool configuration file.

What it does:

• Scans src/tooluniverse/data/*.json for tool configurations
• Creates individual pages in docs/tools/ directory
• Organizes tools by source configuration file
• Generates a master index (tools_config_index.rst)

When to run:

• After adding new tool configuration files
• After modifying tool metadata (name, description, parameters)
• Before committing tool changes

Usage:

cd docs
python generate_config_index.py

Output files:

• docs/tools/tools_config_index.rst - Master catalog
• docs/tools/*_tools.rst - Individual config file pages

Example:

$ python generate_config_index.py
✅ Generated tools_config_index.rst with 42 config files
✅ Created docs/tools/uniprot_tools.rst (25 tools)
✅ Created docs/tools/pubmed_tools.rst (18 tools)

CI/CD Integration: Runs automatically in .github/workflows/deploy-docs.yml

---

generate_tool_reference.py

Purpose: Generates comprehensive tool reference documentation from JSON configurations.

What it does:

• Scans all tool configuration files
• Extracts tool specifications (name, description, parameters, returns)
• Groups tools by category (e.g., Protein, Literature, Chemical)
• Generates detailed reference pages

When to run:

• After adding new tools
• After changing tool schemas
• Before major releases

Usage:

cd docs
python generate_tool_reference.py

Output files:

• docs/tools/tool_reference.rst - Comprehensive tool reference
• Individual category pages (if configured)

CI/CD Integration: Runs automatically in .github/workflows/deploy-docs.yml

---

generate_remote_tools_docs.py

Purpose: Auto-generates documentation for remote tools by scanning their README files.

What it does:

• Scans src/tooluniverse/remote/ for tool directories
• Finds README files (.md, .rst, .txt)
• Converts and embeds READMEs into Sphinx documentation
• Creates navigation structure for remote tools

When to run:

• After adding new remote tools
• After updating remote tool README files
• Before deploying documentation

Usage:

cd docs
python generate_remote_tools_docs.py

Output files:

• docs/tools/remote/*.rst - Individual remote tool pages
• docs/tools/remote_tools_index.rst - Remote tools index

Example:

$ python generate_remote_tools_docs.py
✅ Found 3 remote tools
✅ Generated docs/tools/remote/expert_feedback.rst
✅ Generated docs/tools/remote/custom_api.rst

CI/CD Integration: Runs automatically in .github/workflows/deploy-docs.yml

---

Build Scripts

quick_doc_build.sh

Purpose: Fast local documentation build for development.

What it does:

• Sets DOC_OPTIMIZED=1 for minimal API doc generation
• Runs Sphinx build with warnings as errors
• Opens built HTML in browser
• Skips time-consuming full API generation

When to run:

• During documentation writing/editing
• Before committing documentation changes
• To preview changes locally

Usage:

cd docs
./quick_doc_build.sh

Environment variables:

DOC_OPTIMIZED=1  # Enable fast build mode (minimal API docs)

Build time:

• Normal build: ~3-5 minutes
• Quick build: ~30-60 seconds

Example:

$ ./quick_doc_build.sh
🔧 DOC_OPTIMIZED build enabled - minimal API generation
🏗️  Building documentation...
✅ Build complete! Opening in browser...

Note: Quick builds skip comprehensive API documentation generation. Always run full build (or let CI/CD do it) before releases.

---

quick_build_zh.sh

Purpose: Fast build for Chinese localization documentation.

What it does:

• Builds Chinese language version of documentation
• Uses locale/zh_CN translation files
• Skips API generation for speed

When to run:

• During Chinese translation work
• To preview Chinese documentation

Usage:

cd docs
./quick_build_zh.sh

Prerequisites:

• gettext utilities installed
• Chinese .po translation files in locale/zh_CN/

---

Validation Scripts

validate_examples.py

Purpose: Validates Python code examples in documentation (Chinese comments).

What it does:

• Extracts Python code blocks from RST files
• Checks syntax validity with ast.parse()
• Verifies imports are available
• Reports syntax errors and unavailable imports

When to run:

• Before releases
• After updating code examples
• As part of pre-commit hooks (future)

Usage:

cd docs
python validate_examples.py

Example output:

✅ quickstart.rst: All 5 code blocks valid
❌ advanced.rst: Syntax error in block 3
  Line 12: unexpected indent
✅ All examples validated

Status: Implemented but not yet integrated into CI/CD.

Future integration:

# .github/workflows/deploy-docs.yml
- name: Validate code examples
 run: |
   cd docs
   python validate_examples.py

---

validate_simple.py

Purpose: Unknown (file is currently empty).

Status: Not implemented / unused

Recommendation: Remove this file or implement validation logic.

---

Analysis Scripts

doc_analytics.py

Purpose: Analyzes documentation quality and usage patterns (Chinese comments).

What it does:

• Counts words, lines, headers per page
• Tracks code blocks, links, images
• Identifies pages with missing content
• Generates analytics reports
• Suggests improvements

When to run:

• During quarterly documentation reviews
• To identify improvement opportunities
• For documentation health checks

Usage:

cd docs
python doc_analytics.py

Example output:

{
 "pages": {
   "quickstart.rst": {
     "word_count": 1250,
     "code_blocks": 8,
     "external_links": 5,
     "last_modified": "2024-02-01"
   }
 },
 "recommendations": [
   "installation.rst has no code examples",
   "faq.rst has 50+ external links (consider caching)"
 ]
}

Output: docs/analytics.json

Status: Implemented but not used in CI/CD.

---

doc_sync_tool.py

Purpose: Ensures documentation stays synchronized with source code (Chinese comments).

What it does:

• Extracts docstrings from Python modules
• Compares with RST documentation
• Identifies missing or outdated API docs
• Suggests documentation updates

When to run:

• After significant API changes
• Before major releases
• During API documentation reviews

Usage:

cd docs
python doc_sync_tool.py

Example output:

⚠️  API change detected in tooluniverse.core
  Method `load_tools()` signature changed
  → Update docs/api/tooluniverse.core.rst

✅ 42/45 modules in sync with docs

Status: Implemented but not yet integrated into CI/CD.

Future integration: Consider adding to pre-commit hooks for API changes.

---

Configuration Files

conf.py

Purpose: Sphinx configuration file (not a utility script).

What it contains:

• Sphinx extensions configuration
• Theme settings
• Path configuration
• Build options

When to edit:

• Adding new Sphinx extensions
• Changing theme or styling
• Modifying build behavior

Key settings:

extensions = [
   'sphinx.ext.autodoc',
   'sphinx.ext.napoleon',
   'sphinx_rtd_theme',
]

html_theme = 'sphinx_rtd_theme'

---

Integration with CI/CD

The following scripts are integrated into .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

Why integrated:

• Ensures documentation is always up-to-date with source
• Prevents stale content from being deployed
• Fails build if generation errors occur

Not integrated (but should be considered):

• validate_examples.py - Would catch broken code examples
• doc_sync_tool.py - Would prevent API/docs drift

---

Best Practices

Before Committing Documentation Changes

# 1. Regenerate auto-generated docs
cd docs
python generate_config_index.py
python generate_tool_reference.py
python generate_remote_tools_docs.py

# 2. Build and preview locally
./quick_doc_build.sh

# 3. Validate examples (optional)
python validate_examples.py

# 4. Commit both source and generated files
git add .
git commit -m "docs: update tool reference"

Adding New Tools

# 1. Create tool JSON config
vim src/tooluniverse/data/my_new_tools.json

# 2. Regenerate documentation
cd docs
python generate_config_index.py
python generate_tool_reference.py

# 3. Verify output
ls docs/tools/my_new_tools.rst
grep "My_New_Tool" docs/tools/tools_config_index.rst

# 4. Build locally
./quick_doc_build.sh

Major Documentation Updates

# 1. Run analytics to identify issues
cd docs
python doc_analytics.py
cat analytics.json

# 2. Check API sync status
python doc_sync_tool.py

# 3. Fix identified issues

# 4. Regenerate all auto-generated content
python generate_config_index.py
python generate_tool_reference.py
python generate_remote_tools_docs.py

# 5. Full build test
make clean
make html

# 6. Validate examples
python validate_examples.py

---

Troubleshooting

"Script fails with ModuleNotFoundError"

Problem: Script can't import tooluniverse modules.

Solution: Ensure you're in the correct directory and Python can find the package:

# Set PYTHONPATH
export PYTHONPATH=/path/to/ToolUniverse-main:$PYTHONPATH

# Or install in development mode
pip install -e .

"Generated files not appearing"

Problem: Script runs but no output files created.

Solution: Check for errors in script output:

cd docs
python generate_config_index.py 2>&1 | tee generation.log

Common issues:

• JSON parsing errors in tool configs
• Missing directories (create docs/tools/ manually)
• File permission issues

"Documentation build fails after regeneration"

Problem: Sphinx build errors after running generation scripts.

Solution: Check generated RST syntax:

# Validate RST files
python -m sphinx.cmd.quickstart --dry-run

# Check specific file
rst2html.py docs/tools/problematic_tools.rst > /dev/null

---

Adding New Utility Scripts

When creating new utility scripts, follow this template:

#!/usr/bin/env python3
"""
Brief description of what this script does.

This script [detailed explanation of purpose and functionality].
"""

import sys
from pathlib import Path

def main():
   """Main entry point."""
   # Script logic here
   pass

if __name__ == "__main__":
   main()

Add to this documentation:

1. Add entry to Quick Reference table
2. Create detailed section with:

• Purpose
• What it does
• When to run
• Usage examples
• Output description
• CI/CD integration status

Consider CI/CD integration if:

• Script ensures content freshness
• Script validates correctness
• Script prevents common errors

---

Future Improvements

Planned Enhancements

1. Integrate validation into CI/CD:

• Add validate_examples.py to pre-commit hooks
• Add doc_sync_tool.py to API change detection

2. Create comprehensive validation script:

• Check for broken internal links
• Verify all code examples are tested
• Ensure consistent terminology
• Validate tool counts are up-to-date

3. Automate analytics reporting:

• Generate monthly documentation health reports
• Track documentation coverage metrics
• Identify pages needing updates

4. Improve error handling:

• Better error messages in generation scripts
• Graceful fallbacks for missing files
• Detailed logs for troubleshooting

---

Contact & Questions

For questions about utility scripts:

1. Check this guide first
2. Check DOCUMENTATION_STANDARDS.md
3. Review script source code (all have docstrings)
4. Open GitHub issue with [docs] tag

---

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