doc-generator

Doc Generator

Generates documentation that developers actually read and use — not boilerplate that everyone ignores.

When to Use

• "Write a README for this project"
• "Add docstrings to these functions"
• "Generate API documentation"
• "Write a changelog entry for this release"
• Before open-sourcing or sharing any code

README Generation

A README answers these questions in this order:

1. What is this? (one sentence) Not "a powerful, flexible, enterprise-grade solution" — what does it actually do?

2. Why would I use this? (one paragraph) What problem does it solve? What's the alternative? When should I NOT use it?

3. How do I install it? (one command)

pip install yourpackage

4. How do I use it? (minimal working example) The simplest thing that works, copy-pasteable, tested:

from yourpackage import Thing
result = Thing().do_something("input")
print(result)  # "expected output"

5. Full API / configuration reference Only after the quick example. Developers who need it will scroll; those who don't won't be overwhelmed.

6. Contributing / Development setup How to run tests, how to open a PR.

README Template

# project-name

One sentence: what it does.

## Install

\`\`\`bash
pip install project-name
\`\`\`

## Quick Start

\`\`\`python
[minimal working example]
\`\`\`

## Why project-name?

[problem it solves, who it's for, what makes it different]

## Usage

[fuller examples and configuration]

## API Reference

[function signatures and descriptions]

## Contributing

[how to set up dev environment, run tests, open PRs]

## License

MIT

Docstring Generation

Write docstrings that explain WHY and WHAT, not HOW (the code shows how):

Good:

def chunk_text(text: str, max_tokens: int = 512, overlap: int = 50) -> list[str]:
    """
    Split text into overlapping chunks for RAG ingestion.

    Overlap prevents context loss at chunk boundaries — a sentence split
    across two chunks is still fully recoverable during retrieval.

    Args:
        text: The document text to split. Handles Unicode correctly.
        max_tokens: Target chunk size. Actual chunks may be slightly larger
                    to avoid splitting mid-sentence.
        overlap: Tokens of overlap between consecutive chunks.

    Returns:
        List of text chunks, ordered by position in the original text.

    Raises:
        ValueError: If max_tokens < overlap.
    """