Getting Started¶

Welcome to PyCodeCommenter. This guide will get you from zero to fully documented code in under two minutes.

1. Install¶

We recommend installing PyCodeCommenter inside an active virtual environment so it doesn't conflict with system packages.

pip install pycodecommenter

Requires Python 3.8 or later.

Verify the installation:

pycodecommenter --version

2. Run¶

You don't need to configure anything to run PyCodeCommenter. You just need to point it at a specific Python file.

We recommend running it in dry-run mode first. This allows you to preview the changes safely in your terminal without modifying your actual files:

pycodecommenter generate <path/to/your_file.py> --dry-run

[!TIP] Important: Replace <path/to/your_file.py> with the actual name and location of the file you want to document (for example, main.py or src/utils.py). You can use relative or absolute paths.

Once you've reviewed the proposed docstrings and are happy with them, tell PyCodeCommenter to write the changes directly into your file:

pycodecommenter generate <path/to/your_file.py> --inplace

3. Expected Output¶

When you run the tool, PyCodeCommenter parses your AST (Abstract Syntax Tree), infers the intent from your parameter names and type hints, and generates perfect Google-style docstrings.

Before:

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

After:

def calculate_discount(price: float, rate: float = 0.1) -> float:
    """
    Calculate discount.

    Calculates the discount.

    Args:
        price (float): float value.
        rate (float): float value. Default is 0.1.

    Returns:
        float: Description of the return value.
    """
    return price * (1 - rate)

[!NOTE] PyCodeCommenter is deterministic. It does not use AI or LLMs. It generates a structural starting point that guarantees you meet the syntax requirements of the Google docstring standard.

4. Common Options¶

PyCodeCommenter includes three primary subcommands.

Generate Documentation¶

Generate or update docstrings for a Python file.

# Create backups before modifying
pycodecommenter generate <path/to/your_file.py> --inplace --backup

# Write the result to a new file instead of modifying the original
pycodecommenter generate <path/to/your_file.py> --output <path/to/new_file.py>

Validate Documentation¶

Check if existing docstrings are accurate and match the code's signature.

pycodecommenter validate src/

Exits with code 1 if there are missing arguments or type mismatches in the docstrings.

Check Coverage¶

Get a percentage report of how much of your codebase is documented.

pycodecommenter coverage src/

5. Next Steps¶

Now that you have it running, integrate it into your workflow:

Configuration — set up a .pycodecommenter.yaml to save your CLI flags.
Validation Checks — understand exactly what the validator looks for.
Recipes & CI — copy-paste our GitHub Actions and pre-commit hooks to enforce documentation automatically.