Skip to content

docs-builder.md

Latest commit

 

History

History
246 lines (188 loc) · 5.11 KB

docs-builder.md

File metadata and controls

246 lines (188 loc) · 5.11 KB
Raw
title Documentation Agent
parent Prometheus Agents

The Documentation Builder Agent is a specialized AI tool designed to automatically generate, maintain, and improve project documentation. It analyzes your codebase and creates comprehensive, well-structured documentation that follows best practices.

Key Features

  • Automated Documentation Generation: Creates documentation from code and comments
  • Multiple Format Support: Generates documentation in various formats (Markdown, HTML, PDF)
  • API Documentation: Automatically documents APIs and endpoints
  • Code Examples: Provides relevant code examples and usage patterns
  • Documentation Testing: Validates documentation accuracy and completeness

Usage

1. Basic Documentation Generation

from prometheus_swarm.clients import AnthropicClient
from prometheus_swarm.workflows import DocsBuilderWorkflow
from prometheus_swarm.types import WorkflowConfig

config = WorkflowConfig(
    model="claude-3-opus-20240229",
    output_format="markdown",
    include_examples=True
)

workflow = DocsBuilderWorkflow(config)
docs = workflow.generate_docs("./src")

2. API Documentation

# Generate API documentation
workflow = DocsBuilderWorkflow(config)
api_docs = workflow.generate_api_docs({
    "include_endpoints": True,
    "add_examples": True,
    "test_endpoints": True
})

3. Documentation Update

# Update existing documentation
workflow = DocsBuilderWorkflow(config)
updates = workflow.update_docs({
    "check_outdated": True,
    "add_missing": True,
    "verify_examples": True
})

Documentation Types

1. Code Documentation

  • Function and class documentation
  • Module documentation
  • Type hints and signatures
  • Usage examples
  • Implementation notes

2. API Documentation

  • Endpoint descriptions
  • Request/response formats
  • Authentication methods
  • Rate limits
  • Error handling

3. User Documentation

  • Installation guides
  • Getting started tutorials
  • Configuration guides
  • Troubleshooting guides
  • FAQs

Example Workflow

Here's a complete example of using the Documentation Builder Agent:

from prometheus_swarm.workflows import DocsBuilderWorkflow
from prometheus_swarm.types import WorkflowConfig, DocsSpec

# Define documentation specification
docs_spec = DocsSpec(
    project_name="My Project",
    version="1.0.0",
    source_dirs=["./src", "./api"],
    output_format="markdown",
    sections=[
        "installation",
        "quickstart",
        "api_reference",
        "examples",
        "configuration"
    ],
    options={
        "include_toc": True,
        "add_examples": True,
        "check_links": True,
        "validate_code": True
    }
)

# Configure workflow
config = WorkflowConfig(
    model="claude-3-opus-20240229",
    temperature=0.7
)

# Create and run workflow
workflow = DocsBuilderWorkflow(config)
result = workflow.build_docs(docs_spec)

# Generate site
workflow.generate_site({
    "theme": "material",
    "deploy": True,
    "check_links": True
})

Output Formats

Markdown

  • GitHub Flavored Markdown
  • MkDocs compatibility
  • Jekyll compatibility
  • Hugo compatibility

HTML

  • Static site generation
  • Custom themes
  • Interactive examples
  • Search functionality

PDF

  • Professional formatting
  • Table of contents
  • Cross-references
  • Print optimization

Features

1. Content Generation

  • Automatic structure creation
  • Code analysis and documentation
  • Example generation
  • Cross-referencing

2. Validation

  • Link checking
  • Code example testing
  • API endpoint validation
  • Style consistency

3. Maintenance

  • Outdated content detection
  • Missing documentation alerts
  • Broken link detection
  • Version tracking

Best Practices

  1. Regular Updates: Keep documentation in sync with code changes
  2. Consistent Style: Maintain consistent documentation style
  3. Examples: Include practical examples for complex features
  4. Testing: Validate documentation accuracy regularly
  5. Versioning: Maintain documentation versions with code

Error Handling

try:
    workflow = DocsBuilderWorkflow(config)
    result = workflow.build_docs(docs_spec)
except DocsBuilderError as e:
    if e.error_type == "ContentError":
        print("Content generation failed:", e.details)
    elif e.error_type == "ValidationError":
        print("Validation failed:", e.details)
    else:
        print("Unknown error:", str(e))

Integration

The Documentation Builder Agent integrates with:

Documentation Platforms

  • ReadTheDocs
  • GitHub Pages
  • GitBook
  • MkDocs
  • Sphinx

Version Control

  • Git
  • GitHub
  • GitLab
  • Bitbucket

CI/CD

  • GitHub Actions
  • GitLab CI
  • Jenkins
  • CircleCI

Contributing

To contribute to the Documentation Builder Agent:

  1. Fork the repository
  2. Create a feature branch
  3. Add new documentation features
  4. Add tests for new functionality
  5. Submit a pull request

Future Developments

Planned features include:

  • AI-powered content improvement suggestions
  • More output format support
  • Enhanced API documentation
  • Interactive documentation features
  • Multilingual support
  • Advanced search capabilities