Documentation Workflow¶

This document explains the workflow for generating and maintaining documentation for the Prompt Decorators project.

Overview¶

The documentation for Prompt Decorators consists of:

API Reference: Automatically generated from docstrings, type annotations, and registry data
User Guides: Manually written Markdown files
Examples: Code examples with explanations
Tutorials: Step-by-step guides for common tasks

We use MkDocs with the Material theme to build the documentation website.

Documentation Generation Process¶

The documentation generation process involves two main steps:

Generate API Reference: Extract information from code and registry to create Markdown files
Build Documentation Website: Use MkDocs to build a static website from all Markdown files

Step 1: Generate API Reference¶

To generate the API reference documentation, use the generate_docs.py script in the docs directory:

# Generate documentation
cd docs
python generate_docs.py

# Enable debug mode for verbose output
python generate_docs.py --debug

This script: - Extracts docstrings and type annotations from the code - Loads decorator definitions from the registry - Generates comprehensive documentation for all modules and decorators - Creates well-organized Markdown files in the docs/api directory - Automatically categorizes decorators by their functional domain

Important: docs/generate_docs.py is the sole official documentation generator for the Prompt Decorators project. Any other documentation generators found in the codebase (such as doc_gen.py, generate_api_docs.py, or scripts in the scripts/ directory that generate documentation) are deprecated and should not be used. These deprecated files will be removed in future releases.

Step 2: Build Documentation Website¶

To build the documentation website, use MkDocs:

# Serve documentation locally (with live reload)
mkdocs serve

# Build documentation
mkdocs build

# Deploy documentation to GitHub Pages
mkdocs gh-deploy

Documentation Structure¶

The documentation is organized as follows:

docs/: Root directory for documentation
api/: API reference documentation (auto-generated)
- modules/: Module documentation
- decorators/: Decorator documentation
examples/: Code examples with explanations
guide/: User guides
tutorials/: Step-by-step tutorials
project_summaries/: Project overview and summaries
guides/: Domain-specific guides

Maintaining Documentation¶

Updating API Reference¶

When you make changes to the code:

Update docstrings and type annotations in the code
Run python docs/generate_docs.py to regenerate the API reference
Run mkdocs serve to preview the changes
Commit the changes to the repository

Adding New Decorators¶

When adding new decorators to the registry:

Create the JSON definition file in the appropriate registry directory
Run python docs/generate_docs.py to generate documentation for the new decorator
The documentation will automatically include the decorator in the appropriate category
Verify the generated documentation with mkdocs serve

Adding New Documentation¶

To add new documentation:

Create a new Markdown file in the appropriate directory
Add the file to the navigation in mkdocs.yml
Run mkdocs serve to preview the changes
Commit the changes to the repository

Documentation Standards¶

Please follow these standards when writing documentation:

Docstrings: Use Google-style docstrings (see DOCSTRING_STANDARDS.md)
Markdown: Use consistent formatting and structure
Examples: Include runnable examples that demonstrate key features
Links: Ensure all links are valid and point to the correct location

Troubleshooting¶

Broken Links¶

If you encounter broken links in the documentation:

Run mkdocs build to see warnings about broken links
Fix the broken links in the source files
Regenerate the API reference if necessary
Run mkdocs serve to verify the fixes

Missing Documentation¶

If you notice missing documentation:

Check if the code has proper docstrings and type annotations
Ensure the module or class is included in the documentation generation process
Update the docstrings and regenerate the API reference
Update the navigation in mkdocs.yml if necessary