PyCodeCommenter 🚀

The Python documentation tool that developers actually want to use.

PyCodeCommenter automatically generates, validates, and maintains Google-style docstrings for your Python code. Unlike AI-based tools, it provides deterministic, rule-based validation that catches documentation issues AI might miss.

Why PyCodeCommenter?

The Problem

• AI tools generate inconsistent documentation
• No way to validate existing docstrings against code
• Documentation drift as code evolves
• No coverage metrics for documentation quality

The Solution

• Generate professional docstrings automatically
• Validate existing docs against actual code signatures
• Track documentation coverage across projects
• Integrate with CI/CD pipelines

Terminal Usage

# Generate docstrings for a file
pycodecommenter generate main.py -i

# Validate documentation
pycodecommenter validate main.py

# Check project coverage
pycodecommenter coverage .

Features

Comprehensive Validation

Six types of validation checks:

• Signature Matching: Params in code match docstring
• Type Consistency: Type hints match documented types
• Exception Documentation: Raised exceptions are documented
• Return Documentation: Return values properly documented
• Format Compliance: Follows Google-style guidelines
• Content Quality: No placeholders or TODOs

Coverage Reporting

• Per-file coverage metrics
• Project-wide statistics
• Export to JSON, Markdown, or console
• CI/CD integration ready

Modern Python Support

• Python 3.8+ support
• Async functions (async def)
• Complex type hints (Union, Optional, Generic)
• PEP 604 unions (int | str)
• PEP 585 generics (list[int])

Developer-Friendly

• Beautiful console output
• Actionable error messages
• Multiple export formats
• Fast AST-based analysis (no API calls)

Usage Examples

Example 1: Basic Generation

from PyCodeCommenter import PyCodeCommenter

code = """
def calculate_discount(price: float, rate: float = 0.1) -> float:
    return price * (1 - rate)
"""

commenter = PyCodeCommenter().from_string(code)
docstrings = commenter.generate_docstrings()
print(commenter.get_patched_code())

Output:

def calculate_discount(price: float, rate: float = 0.1) -> float:
    """Calculate discount.
    
    Calculates the discount.
    
    Args:
        price (float): Price of the object.
        rate (float): Rate of the object. (default: 0.1)
    
    Returns:
        float: Description of the return value.
    """
    return price * (1 - rate)

Example 2: Validation in CI/CD

# validate_docs.py
import sys
from PyCodeCommenter import PyCodeCommenter

commenter = PyCodeCommenter().from_file("src/main.py")
report = commenter.validate()

if report.stats.errors > 0:
    report.print_summary()
    sys.exit(1)  # Fail CI build

print(f"✓ Documentation validated: {report.stats.coverage_percentage:.1f}% coverage")

Example 3: Coverage Enforcement

from PyCodeCommenter import CoverageAnalyzer

analyzer = CoverageAnalyzer()
project = analyzer.analyze_directory("./src", exclude_patterns=['tests'])

if project.total_coverage < 80.0:
    print(f"❌ Coverage {project.total_coverage:.1f}% below threshold 80%")
    project.print_report()
    sys.exit(1)

print(f"✓ Coverage {project.total_coverage:.1f}% meets threshold")

Example 4: Export Reports

import json
from PyCodeCommenter import PyCodeCommenter

commenter = PyCodeCommenter().from_file("mycode.py")
report = commenter.validate()

# JSON export
with open("validation_report.json", "w") as f:
    json.dump(report.to_dict(), f, indent=2)

# Markdown export
with open("validation_report.md", "w") as f:
    f.write(report.to_markdown())

Configuration

Create .pycodecommenter.yaml in your project root:

style: google  # or 'numpy', 'sphinx'
validation:
  level: strict  # or 'moderate', 'lenient'
  check_types: true
  check_exceptions: true
coverage:
  threshold: 80
  fail_below: true
exclude:
  - "*/tests/*"
  - "*/migrations/*"
  - "*/__pycache__/*"

Use Cases

For Individual Developers

• Generate documentation for new functions quickly
• Validate docs before committing
• Track documentation coverage

For Teams

• Enforce documentation standards in CI/CD
• Prevent PRs with undocumented code
• Maintain consistent documentation style

For Open Source Projects

• Welcome contributors with clear doc requirements
• Automated documentation checks in PRs
• Public coverage badges

Integration

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: validate-docstrings
        name: Validate Docstrings
        entry: pycodecommenter validate .
        language: system
        types: [python]

GitHub Actions

# .github/workflows/docs.yml
name: Documentation Check

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: pip install pycodecommenter
      - name: Validate documentation
        run: pycodecommenter validate .

Documentation

• User Guide - Comprehensive usage guide
• API Reference - Complete API documentation
• Configuration - Configuration options
• Contributing - How to contribute

Known Limitations

• Does not support Python 2.x (EOL)
• Match statements (Python 3.10+) have basic support
• Complex decorators may affect docstring placement

Roadmap

• VS Code extension
• Smart docstring updates (preserve human content)
• AI-powered generation (optional)
• NumPy and Sphinx style support
• GitHub Action for automated PRs

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Show Your Support

If PyCodeCommenter helped you, please star the repo! It helps others discover the project.

Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions