Dynamic Documentation System

Overview

This system automatically generates API documentation for the four context variables (market, portfolio, memory, session) by extracting information directly from the Python source code.

How It Works

1. Python Introspection Tool (tools/extract-python-api.py)

• Uses Python's inspect module to analyze classes
• Extracts properties, methods, docstrings, type hints
• Generates structured JSON with comprehensive API information
• Runs automatically during documentation builds

2. VitePress Data Loader (.vitepress/data/pythonApi.data.js)

• Loads the generated JSON at build time
• Transforms data for easier consumption by Vue components
• Makes API data available to all documentation pages

3. Vue Components

• ApiReference.vue: Full API documentation with properties, methods, and examples
• ApiSummary.vue: Compact API overview with quick references

4. Integration

• Updated strategy-development/syntax-reference.md to use new dynamic components
• Automatic API extraction in npm build scripts
• Updated variable names to use new naming (market, portfolio, memory, session)

Usage

In Documentation Pages

<!-- Full API reference -->
<ApiReference context="market" />

<!-- Quick summary -->
<ApiSummary context="portfolio" />

Build Process

# Normal documentation build (uses pre-generated API data)
npm run docs:build

# Development with live updates
npm run docs:dev

# Regenerate API documentation (when backtesting-engine code changes)
npm run regenerate-api

When to Regenerate API Documentation

The API documentation is pre-generated and committed to the repository for build reliability. You only need to regenerate it when:

1. Backtesting engine API changes: New properties, methods, or docstrings added/modified
2. Context class changes: Changes to DataContext, PortfolioContext, or SessionInfo classes
3. Method signatures change: Parameter types, names, or return types modified

API Regeneration Workflow

# 1. Make changes to backtesting-engine code
cd ../backtesting-engine
# ... make your changes ...

# 2. Regenerate documentation (requires Python + pandas)
cd ../docs
npm run regenerate-api

# 3. Commit the updated documentation
git add .vitepress/data/python-api.json
git commit -m "docs: update API documentation for [describe changes]"

Important: The documentation build process no longer requires Python dependencies in CI. The pre-generated python-api.json file ensures reliable builds.

Generated Documentation Includes

For each context variable:

• Class Information: Name, module, description
• Properties: Type, description, readonly status, examples
• Methods: Signature, parameters, return types, examples
• Usage Examples: Common patterns and code snippets
• Generation Metadata: Timestamp, version info

Benefits

1. Always Accurate: Documentation reflects actual code structure
2. Zero Maintenance: Updates automatically when Python code changes
3. Comprehensive: Captures all public members, not just manually documented ones
4. Consistent: Uniform formatting across all API documentation
5. Live Updates: Changes in Python code immediately appear in docs

Files Created/Modified

New Files

• docs/tools/extract-python-api.py - Python introspection tool
• docs/.vitepress/data/pythonApi.data.js - VitePress data loader
• docs/.vitepress/components/ApiReference.vue - Full API component
• docs/.vitepress/components/ApiSummary.vue - Summary API component
• docs/.vitepress/theme/index.js - Theme configuration
• docs/.vitepress/theme/custom.css - Custom styles
• docs/.vitepress/data/python-api.json - Generated API data

Modified Files

• docs/package.json - Added API extraction to build scripts
• docs/strategy-development/syntax-reference.md - Updated with dynamic components
• docs/.vitepress/config.mjs - VitePress configuration

Technical Details

The system works by:

1. Pre-generated API data: python-api.json is committed to the repository
2. VitePress data loader: Makes API data available as pythonApiData at build time
3. Vue components: Render the documentation dynamically from JSON data
4. Manual regeneration: npm run regenerate-api updates the JSON when needed
5. CI-friendly: No Python dependencies required for documentation builds

Future Enhancements

• Add search functionality across API members
• Generate type definitions for TypeScript users
• Add interactive code examples
• Include performance metrics for methods
• Add changelog tracking for API changes