Auto-generate and sync project documentation from source code analysis

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for tom-sapletta-com from gravatar.com tom-sapletta-com

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License Expression: Apache-2.0
    SPDX License Expression
  • Author: Tom Sapletta
  • Tags documentation , auto-docs , readme-generator , api-reference , code-analysis , static-analysis , markdown
  • Requires: Python >=3.9
  • Provides-Extra: llm , git , watch , mkdocs , dev , all
Classifiers
Report project as malware

Project description

code2docs

AI Cost Tracking

PyPI Version Python License AI Cost Human Time Model

  • ๐Ÿค– LLM usage: $7.5000 (52 commits)
  • ๐Ÿ‘ค Human dev: ~$1621 (16.2h @ $100/h, 30min dedup)

Generated on 2026-03-31 using openrouter/qwen/qwen3-coder-next

version python docs

Auto-generate and sync project documentation from source code analysis.

code2docs uses code2llm's AnalysisResult to produce human-readable documentation: README.md, API references, module docs, usage examples, and architecture diagrams.

code2llm  โ†’  AnalysisResult  โ†’  .toon / .mmd / context.md   (for LLM)
code2docs โ†’  AnalysisResult  โ†’  README.md / docs/ / examples/  (for humans)

Installation

pip install code2docs

Or from source:

git clone https://github.com/wronai/code2docs
cd code2docs
pip install -e .

Optional extras

pip install code2docs[watch]    # file watcher (watchdog)
pip install code2docs[mkdocs]   # MkDocs integration
pip install code2docs[dev]      # development tools

Quick Start

# Generate full documentation for a project
code2docs ./my-project

# Generate only README
code2docs ./my-project --readme-only

# Sync (regenerate only changed modules)
code2docs sync ./my-project

# Watch mode (auto-resync on file changes)
code2docs watch ./my-project

# Initialize config file
code2docs init ./my-project

# Dry-run (show what would be generated)
code2docs ./my-project --dry-run

Python API

from code2docs import generate_readme, generate_docs, Code2DocsConfig

# Generate README
generate_readme("./my-project", output="README.md")

# Generate full docs with custom config
config = Code2DocsConfig(project_name="mylib", verbose=True)
docs = generate_docs("./my-project", config=config)

Generated Output

<project>/
โ”œโ”€โ”€ README.md                      # Main README (auto-generated sections)
โ”œโ”€โ”€ docs/
โ”‚   โ”œโ”€โ”€ index.md                   # Documentation index
โ”‚   โ”œโ”€โ”€ architecture.md            # Architecture + Mermaid diagrams
โ”‚   โ”œโ”€โ”€ api/
โ”‚   โ”‚   โ”œโ”€โ”€ index.md               # API overview
โ”‚   โ”‚   โ”œโ”€โ”€ module_analyzer.md     # Per-module API reference
โ”‚   โ”‚   โ””โ”€โ”€ ...
โ”‚   โ””โ”€โ”€ modules/
โ”‚       โ”œโ”€โ”€ analyzer.md            # Detailed module documentation
โ”‚       โ””โ”€โ”€ ...
โ”œโ”€โ”€ examples/
โ”‚   โ”œโ”€โ”€ basic_usage.py             # Auto-generated usage example
โ”‚   โ”œโ”€โ”€ class_examples.py          # Class usage examples
โ”‚   โ””โ”€โ”€ ...
โ””โ”€โ”€ code2docs.yaml                 # Generator configuration

Configuration

Create code2docs.yaml in your project root (or run code2docs init):

project:
  name: my-project
  source: ./
  output: ./docs/

readme:
  sections:
    - overview
    - install
    - quickstart
    - api
    - structure
    - endpoints
  badges:
    - version
    - python
    - coverage
    - complexity
  sync_markers: true

docs:
  api_reference: true
  module_docs: true
  architecture: true
  changelog: true

examples:
  auto_generate: true
  from_entry_points: true

sync:
  strategy: markers    # markers | full | git-diff
  watch: false
  ignore:
    - "tests/"
    - "__pycache__"

Sync Markers

code2docs can update only specific sections of an existing README using markers:

<!-- code2docs:start --># code2docs

![version](https://img.shields.io/badge/version-3.0.25-blue) ![python](https://img.shields.io/badge/python-%3E%3D3.9-blue) ![coverage](https://img.shields.io/badge/coverage-unknown-lightgrey) ![functions](https://img.shields.io/badge/functions-276-green)
> **276** functions | **57** classes | **51** files | CCฬ„ = 3.8

> Auto-generated project documentation from source code analysis.

**Author:** Tom Sapletta  
**License:** Apache-2.0[(LICENSE)](./LICENSE)  
**Repository:** [https://github.com/wronai/code2docs](https://github.com/wronai/code2docs)

## Installation

### From PyPI

```bash
pip install code2docs

From Source

git clone https://github.com/wronai/code2docs
cd code2docs
pip install -e .

Optional Extras

pip install code2docs[llm]    # LLM integration (litellm)
pip install code2docs[git]    # Git integration (GitPython)
pip install code2docs[watch]    # file watcher (watchdog)
pip install code2docs[mkdocs]    # MkDocs integration
pip install code2docs[dev]    # development tools
pip install code2docs[all]    # all optional features

Quick Start

CLI Usage

# Generate full documentation for your project
code2docs ./my-project

# Only regenerate README
code2docs ./my-project --readme-only

# Preview what would be generated (no file writes)
code2docs ./my-project --dry-run

# Check documentation health
code2docs check ./my-project

# Sync โ€” regenerate only changed modules
code2docs sync ./my-project

Python API

from code2docs import generate_readme, generate_docs, Code2DocsConfig

# Quick: generate README
generate_readme("./my-project")

# Full: generate all documentation
config = Code2DocsConfig(project_name="mylib", verbose=True)
docs = generate_docs("./my-project", config=config)

Generated Output

When you run code2docs, the following files are produced:

<project>/
โ”œโ”€โ”€ README.md                 # Main project README (auto-generated sections)
โ”œโ”€โ”€ docs/
โ”‚   โ”œโ”€โ”€ api.md               # Consolidated API reference
โ”‚   โ”œโ”€โ”€ modules.md           # Module documentation with metrics
โ”‚   โ”œโ”€โ”€ architecture.md      # Architecture overview with diagrams
โ”‚   โ”œโ”€โ”€ dependency-graph.md  # Module dependency graphs
โ”‚   โ”œโ”€โ”€ coverage.md          # Docstring coverage report
โ”‚   โ”œโ”€โ”€ getting-started.md   # Getting started guide
โ”‚   โ”œโ”€โ”€ configuration.md    # Configuration reference
โ”‚   โ””โ”€โ”€ api-changelog.md    # API change tracking
โ”œโ”€โ”€ examples/
โ”‚   โ”œโ”€โ”€ quickstart.py       # Basic usage examples
โ”‚   โ””โ”€โ”€ advanced_usage.py   # Advanced usage examples
โ”œโ”€โ”€ CONTRIBUTING.md         # Contribution guidelines
โ””โ”€โ”€ mkdocs.yml             # MkDocs site configuration

Configuration

Create code2docs.yaml in your project root (or run code2docs init):

project:
  name: my-project
  source: ./
  output: ./docs/

readme:
  sections:
    - overview
    - install
    - quickstart
    - api
    - structure
  badges:
    - version
    - python
    - coverage
  sync_markers: true

docs:
  api_reference: true
  module_docs: true
  architecture: true
  changelog: true

examples:
  auto_generate: true
  from_entry_points: true

sync:
  strategy: markers    # markers | full | git-diff
  watch: false
  ignore:
    - "tests/"
    - "__pycache__"

Sync Markers

code2docs can update only specific sections of an existing README using HTML comment markers:

<!-- code2docs:start -->
# Project Title
... auto-generated content ...
<!-- code2docs:end -->

Content outside the markers is preserved when regenerating. Enable this with sync_markers: true in your configuration.

Architecture

code2docs/
    โ”œโ”€โ”€ registry    โ”œโ”€โ”€ llm_helperโ”œโ”€โ”€ code2docs/    โ”œโ”€โ”€ __main__    โ”œโ”€โ”€ 04_sync_and_watch    โ”œโ”€โ”€ 05_custom_generators    โ”œโ”€โ”€ quickstart    โ”œโ”€โ”€ 06_formatters    โ”œโ”€โ”€ advanced_usage    โ”œโ”€โ”€ 03_programmatic_api    โ”œโ”€โ”€ entry_points    โ”œโ”€โ”€ 07_web_frameworks    โ”œโ”€โ”€ class_examples    โ”œโ”€โ”€ basic_usage    โ”œโ”€โ”€ 01_cli_usage    โ”œโ”€โ”€ 02_configuration        โ”œโ”€โ”€ updater    โ”œโ”€โ”€ sync/        โ”œโ”€โ”€ watcher    โ”œโ”€โ”€ base        โ”œโ”€โ”€ quickstart        โ”œโ”€โ”€ advanced_usage        โ”œโ”€โ”€ markdown        โ”œโ”€โ”€ badges        โ”œโ”€โ”€ toc    โ”œโ”€โ”€ formatters/        โ”œโ”€โ”€ differ        โ”œโ”€โ”€ coverage_gen        โ”œโ”€โ”€ _source_links        โ”œโ”€โ”€ depgraph_gen        โ”œโ”€โ”€ getting_started_gen        โ”œโ”€โ”€ config_docs_gen        โ”œโ”€โ”€ changelog_gen    โ”œโ”€โ”€ generators/        โ”œโ”€โ”€ code2llm_gen        โ”œโ”€โ”€ module_docs_gen        โ”œโ”€โ”€ api_reference_gen        โ”œโ”€โ”€ examples_gen        โ”œโ”€โ”€ mkdocs_gen    โ”œโ”€โ”€ config        โ”œโ”€โ”€ api_changelog_gen        โ”œโ”€โ”€ _registry_adapters        โ”œโ”€โ”€ readme_gen        โ”œโ”€โ”€ contributing_gen    โ”œโ”€โ”€ analyzers/        โ”œโ”€โ”€ dependency_scanner        โ”œโ”€โ”€ endpoint_detector        โ”œโ”€โ”€ architecture_gen        โ”œโ”€โ”€ project_scanner        โ”œโ”€โ”€ docstring_extractor    โ”œโ”€โ”€ cli```

## API Overview

### Classes

- **`GeneratorRegistry`** โ€” Registry of documentation generators.
- **`LLMHelper`** โ€” Thin wrapper around litellm for documentation generation.
- **`MetricsReportGenerator`** โ€” Generate a metrics report from code analysis.
- **`APIChangelogGenerator`** โ€” Generate changelog based on API changes.
- **`CustomGenerator`** โ€” Example of extending the base generator class.
- **`Updater`** โ€” Apply selective documentation updates based on detected changes.
- **`GenerateContext`** โ€” Shared context passed to all generators during a run.
- **`BaseGenerator`** โ€” Abstract base for all documentation generators.
- **`MarkdownFormatter`** โ€” Helper for constructing Markdown documents.
- **`ChangeInfo`** โ€” Describes a detected change.
- **`Differ`** โ€” Detect changes between current source and previous state.
- **`CoverageGenerator`** โ€” Generate docs/coverage.md โ€” docstring coverage report.
- **`SourceLinker`** โ€” Build source-code links (relative paths + optional GitHub/GitLab URLs).
- **`DepGraphGenerator`** โ€” Generate docs/dependency-graph.md with Mermaid diagrams.
- **`GettingStartedGenerator`** โ€” Generate docs/getting-started.md from entry points and dependencies.
- **`ConfigDocsGenerator`** โ€” Generate docs/configuration.md from Code2DocsConfig dataclass.
- **`ChangelogEntry`** โ€” A single changelog entry.
- **`ChangelogGenerator`** โ€” Generate CHANGELOG.md from git log and analysis diff.
- **`Code2LlmGenerator`** โ€” Generate code2llm analysis files in project/ directory.
- **`ModuleDocsGenerator`** โ€” Generate docs/modules.md โ€” consolidated module documentation.
- **`ApiReferenceGenerator`** โ€” Generate docs/api.md โ€” consolidated API reference.
- **`ExamplesGenerator`** โ€” Generate examples/ โ€” usage examples from public API signatures.
- **`MkDocsGenerator`** โ€” Generate mkdocs.yml from the docs/ directory structure.
- **`ReadmeConfig`** โ€” Configuration for README generation.
- **`DocsConfig`** โ€” Configuration for docs/ generation.
- **`ExamplesConfig`** โ€” Configuration for examples/ generation.
- **`SyncConfig`** โ€” Configuration for synchronization.
- **`Code2LlmConfig`** โ€” Configuration for code2llm analysis generation.
- **`LLMConfig`** โ€” Configuration for optional LLM-assisted documentation generation.
- **`Code2DocsConfig`** โ€” Main configuration for code2docs.
- **`ApiChange`** โ€” A single API change between two analysis snapshots.
- **`ApiChangelogGenerator`** โ€” Generate API changelog by diffing current analysis with a saved snapshot.
- **`ReadmeGeneratorAdapter`** โ€” โ€”
- **`ApiReferenceAdapter`** โ€” โ€”
- **`ModuleDocsAdapter`** โ€” โ€”
- **`ArchitectureAdapter`** โ€” โ€”
- **`DepGraphAdapter`** โ€” โ€”
- **`CoverageAdapter`** โ€” โ€”
- **`ApiChangelogAdapter`** โ€” โ€”
- **`ExamplesAdapter`** โ€” โ€”
- **`MkDocsAdapter`** โ€” โ€”
- **`GettingStartedAdapter`** โ€” โ€”
- **`ConfigDocsAdapter`** โ€” โ€”
- **`ContributingAdapter`** โ€” โ€”
- **`Code2LlmAdapter`** โ€” Adapter for code2llm analysis generation.
- **`ReadmeGenerator`** โ€” Generate README.md from AnalysisResult.
- **`ContributingGenerator`** โ€” Generate CONTRIBUTING.md by detecting dev tools from pyproject.toml.
- **`DependencyInfo`** โ€” Information about a project dependency.
- **`ProjectDependencies`** โ€” All detected project dependencies.
- **`DependencyScanner`** โ€” Scan and parse project dependency files.
- **`Endpoint`** โ€” Represents a detected web endpoint.
- **`EndpointDetector`** โ€” Detects web endpoints from decorator patterns in source code.
- **`ArchitectureGenerator`** โ€” Generate docs/architecture.md โ€” architecture overview with diagrams.
- **`ProjectScanner`** โ€” Wraps code2llm's ProjectAnalyzer with code2docs-specific defaults.
- **`DocstringInfo`** โ€” Parsed docstring with sections.
- **`DocstringExtractor`** โ€” Extract and parse docstrings from AnalysisResult.
- **`DefaultGroup`** โ€” Click Group that routes unknown subcommands to 'generate'.

### Functions

- `detect_changes_example(project_path)` โ€” Detect what files have changed since last documentation generation.
- `update_docs_incrementally(project_path)` โ€” Update only the parts of docs that need changing.
- `force_full_regeneration(project_path)` โ€” Force full regeneration of all documentation.
- `watch_and_auto_regenerate(project_path, interval)` โ€” Watch for file changes and auto-regenerate documentation.
- `custom_watcher_with_hooks(project_path)` โ€” Set up a custom watcher with pre/post generation hooks.
- `sync_with_git_changes(project_path)` โ€” Only regenerate docs for files changed in git.
- `generate_custom_report(project_path)` โ€” Generate a custom metrics report.
- `markdown_formatting_examples()` โ€” Demonstrate markdown formatting utilities.
- `generate_complex_document()` โ€” Generate a complex markdown document using the formatter.
- `badge_examples()` โ€” Generate various badge examples.
- `toc_examples()` โ€” Demonstrate table of contents generation.
- `build_custom_readme()` โ€” Build a custom README using formatters.
- `generate_readme_simple(project_path)` โ€” Generate README.md content from a project.
- `generate_full_documentation(project_path)` โ€” Generate complete documentation for a project.
- `custom_documentation_pipeline(project_path)` โ€” Create a custom documentation pipeline.
- `inspect_project_structure(project_path)` โ€” Inspect project structure from analysis.
- `generate_docs_if_needed(project_path, force)` โ€” Only generate docs if code has changed.
- `detect_flask_endpoints(project_path)` โ€” Detect Flask endpoints in a project.
- `detect_fastapi_endpoints(project_path)` โ€” Detect FastAPI endpoints in a project.
- `generate_api_docs_from_endpoints(project_path, output_dir)` โ€” Generate API documentation from detected endpoints.
- `create_example_web_apps(target_dir)` โ€” Create example Flask and FastAPI apps for testing.
- `document_web_project(project_path)` โ€” Complete workflow: detect endpoints and generate docs.
- `run_cli_basic(project_path)` โ€” Run code2docs CLI programmatically.
- `run_cli_with_config(project_path, config_path)` โ€” Run with custom configuration.
- `create_basic_config()` โ€” Create a basic configuration.
- `create_advanced_config()` โ€” Create advanced configuration with all options.
- `save_yaml_config_example(path)` โ€” Save example YAML config to file.
- `load_config_from_yaml(path)` โ€” Load configuration from YAML file.
- `start_watcher(project_path, config)` โ€” Start watching project for file changes and auto-resync docs.
- `generate_badges(project_name, badge_types, stats, deps)` โ€” Generate shields.io badge Markdown strings.
- `generate_toc(markdown_content, max_depth)` โ€” Generate a table of contents from Markdown headings.
- `extract_headings(content, max_depth)` โ€” Extract headings from Markdown content.
- `generate_docs(project_path, config)` โ€” High-level function to generate all documentation.
- `generate_code2llm_analysis(project_path, config)` โ€” Convenience function to generate code2llm analysis.
- `generate_readme(project_path, output, sections, sync_markers)` โ€” Convenience function to generate a README.
- `analyze_and_document(project_path, config)` โ€” Convenience function: analyze a project in one call.
- `main()` โ€” code2docs โ€” Auto-generate project documentation from source code.
- `generate(project_path, config_path, readme_only, sections)` โ€” Generate documentation (default command).
- `sync(project_path, config_path, verbose, dry_run)` โ€” Synchronize documentation with source code changes.
- `watch(project_path, config_path, verbose)` โ€” Watch for file changes and auto-regenerate docs.
- `init(project_path, output)` โ€” Initialize code2docs.yaml configuration file.
- `check(project_path, config_path, target)` โ€” Health check โ€” verify documentation completeness.
- `diff(project_path, config_path)` โ€” Preview what would change without writing anything.


## Project Structure

๐Ÿ“ฆ `code2docs` (1 functions)
๐Ÿ“„ `code2docs.__main__`
๐Ÿ“ฆ `code2docs.analyzers`
๐Ÿ“„ `code2docs.analyzers.dependency_scanner` (6 functions, 3 classes)
๐Ÿ“„ `code2docs.analyzers.docstring_extractor` (10 functions, 2 classes)
๐Ÿ“„ `code2docs.analyzers.endpoint_detector` (3 functions, 2 classes)
๐Ÿ“„ `code2docs.analyzers.project_scanner` (4 functions, 1 classes)
๐Ÿ“„ `code2docs.base` (3 functions, 2 classes)
๐Ÿ“„ `code2docs.cli` (14 functions, 1 classes)
๐Ÿ“„ `code2docs.config` (5 functions, 7 classes)
๐Ÿ“„ `code2docs.examples.advanced_usage`
๐Ÿ“„ `code2docs.examples.quickstart`
๐Ÿ“ฆ `code2docs.formatters`
๐Ÿ“„ `code2docs.formatters.badges` (2 functions)
๐Ÿ“„ `code2docs.formatters.markdown` (13 functions, 1 classes)
๐Ÿ“„ `code2docs.formatters.toc` (3 functions)
๐Ÿ“ฆ `code2docs.generators` (1 functions)
๐Ÿ“„ `code2docs.generators._registry_adapters` (26 functions, 13 classes)
๐Ÿ“„ `code2docs.generators._source_links` (6 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.api_changelog_gen` (9 functions, 2 classes)
๐Ÿ“„ `code2docs.generators.api_reference_gen` (7 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.architecture_gen` (10 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.changelog_gen` (6 functions, 2 classes)
๐Ÿ“„ `code2docs.generators.code2llm_gen` (5 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.config_docs_gen` (4 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.contributing_gen` (8 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.coverage_gen` (7 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.depgraph_gen` (9 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.examples_gen` (14 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.getting_started_gen` (8 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.mkdocs_gen` (4 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.module_docs_gen` (9 functions, 1 classes)
๐Ÿ“„ `code2docs.generators.readme_gen` (18 functions, 1 classes)
๐Ÿ“„ `code2docs.llm_helper` (7 functions, 1 classes)
๐Ÿ“„ `code2docs.registry` (4 functions, 1 classes)
๐Ÿ“ฆ `code2docs.sync`
๐Ÿ“„ `code2docs.sync.differ` (7 functions, 2 classes)
๐Ÿ“„ `code2docs.sync.updater` (2 functions, 1 classes)
๐Ÿ“„ `code2docs.sync.watcher` (1 functions)
๐Ÿ“„ `examples.01_cli_usage` (2 functions)
๐Ÿ“„ `examples.02_configuration` (4 functions)
๐Ÿ“„ `examples.03_programmatic_api` (5 functions)
๐Ÿ“„ `examples.04_sync_and_watch` (6 functions)
๐Ÿ“„ `examples.05_custom_generators` (13 functions, 3 classes)
๐Ÿ“„ `examples.06_formatters` (5 functions)
๐Ÿ“„ `examples.07_web_frameworks` (5 functions)
๐Ÿ“„ `examples.advanced_usage`
๐Ÿ“„ `examples.basic_usage`
๐Ÿ“„ `examples.class_examples`
๐Ÿ“„ `examples.entry_points`
๐Ÿ“„ `examples.quickstart`

## Requirements

- Python >= >=3.9
- code2llm >=0.5.0- jinja2 >=3.1- click >=8.0- pyyaml >=6.0- rich >=13.0

## Contributing

**Contributors:**
- Tom Softreck <tom@sapletta.com>
- Tom Sapletta <tom-sapletta-com@users.noreply.github.com>

We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/wronai/code2docs
cd code2docs

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

Documentation

Generated Files

Output Description Link
README.md Project overview (this file) โ€”
docs/api.md Consolidated API reference View
docs/modules.md Module reference with metrics View
docs/architecture.md Architecture with diagrams View
docs/dependency-graph.md Dependency graphs View
docs/coverage.md Docstring coverage report View
docs/getting-started.md Getting started guide View
docs/configuration.md Configuration reference View
docs/api-changelog.md API change tracking View
CONTRIBUTING.md Contribution guidelines View
examples/ Usage examples Browse
mkdocs.yml MkDocs configuration โ€” 

Content outside the markers is preserved when regenerating. Enable this with `sync_markers: true` in your configuration.

## Architecture

code2docs/ โ”œโ”€โ”€ registry โ”œโ”€โ”€ llm_helperโ”œโ”€โ”€ code2docs/ โ”œโ”€โ”€ main โ”œโ”€โ”€ 04_sync_and_watch โ”œโ”€โ”€ 05_custom_generators โ”œโ”€โ”€ 06_formatters โ”œโ”€โ”€ 03_programmatic_api โ”œโ”€โ”€ entry_points โ”œโ”€โ”€ 07_web_frameworks โ”œโ”€โ”€ class_examples โ”œโ”€โ”€ basic_usage โ”œโ”€โ”€ 01_cli_usage โ”œโ”€โ”€ 02_configuration โ”œโ”€โ”€ updater โ”œโ”€โ”€ sync/ โ”œโ”€โ”€ watcher โ”œโ”€โ”€ differ โ”œโ”€โ”€ quickstart โ”œโ”€โ”€ base โ”œโ”€โ”€ advanced_usage โ”œโ”€โ”€ badges โ”œโ”€โ”€ markdown โ”œโ”€โ”€ formatters/ โ”œโ”€โ”€ toc โ”œโ”€โ”€ coverage_gen โ”œโ”€โ”€ _source_links โ”œโ”€โ”€ depgraph_gen โ”œโ”€โ”€ getting_started_gen โ”œโ”€โ”€ config_docs_gen โ”œโ”€โ”€ changelog_gen โ”œโ”€โ”€ generators/ โ”œโ”€โ”€ code2llm_gen โ”œโ”€โ”€ module_docs_gen โ”œโ”€โ”€ api_reference_gen โ”œโ”€โ”€ examples_gen โ”œโ”€โ”€ mkdocs_gen โ”œโ”€โ”€ config โ”œโ”€โ”€ api_changelog_gen โ”œโ”€โ”€ _registry_adapters โ”œโ”€โ”€ contributing_gen โ”œโ”€โ”€ readme_gen โ”œโ”€โ”€ analyzers/ โ”œโ”€โ”€ docstring_extractor โ”œโ”€โ”€ endpoint_detector โ”œโ”€โ”€ architecture_gen โ”œโ”€โ”€ project_scanner โ”œโ”€โ”€ cli โ”œโ”€โ”€ dependency_scanner```

API Overview

Classes

  • GeneratorRegistry โ€” Registry of documentation generators.
  • LLMHelper โ€” Thin wrapper around litellm for documentation generation.
  • MetricsReportGenerator โ€” Generate a metrics report from code analysis.
  • APIChangelogGenerator โ€” Generate changelog based on API changes.
  • CustomGenerator โ€” Example of extending the base generator class.
  • Updater โ€” Apply selective documentation updates based on detected changes.
  • ChangeInfo โ€” Describes a detected change.
  • Differ โ€” Detect changes between current source and previous state.
  • GenerateContext โ€” Shared context passed to all generators during a run.
  • BaseGenerator โ€” Abstract base for all documentation generators.
  • MarkdownFormatter โ€” Helper for constructing Markdown documents.
  • CoverageGenerator โ€” Generate docs/coverage.md โ€” docstring coverage report.
  • SourceLinker โ€” Build source-code links (relative paths + optional GitHub/GitLab URLs).
  • DepGraphGenerator โ€” Generate docs/dependency-graph.md with Mermaid diagrams.
  • GettingStartedGenerator โ€” Generate docs/getting-started.md from entry points and dependencies.
  • ConfigDocsGenerator โ€” Generate docs/configuration.md from Code2DocsConfig dataclass.
  • ChangelogEntry โ€” A single changelog entry.
  • ChangelogGenerator โ€” Generate CHANGELOG.md from git log and analysis diff.
  • Code2LlmGenerator โ€” Generate code2llm analysis files in project/ directory.
  • ModuleDocsGenerator โ€” Generate docs/modules.md โ€” consolidated module documentation.
  • ApiReferenceGenerator โ€” Generate docs/api.md โ€” consolidated API reference.
  • ExamplesGenerator โ€” Generate examples/ โ€” usage examples from public API signatures.
  • MkDocsGenerator โ€” Generate mkdocs.yml from the docs/ directory structure.
  • ReadmeConfig โ€” Configuration for README generation.
  • DocsConfig โ€” Configuration for docs/ generation.
  • ExamplesConfig โ€” Configuration for examples/ generation.
  • SyncConfig โ€” Configuration for synchronization.
  • Code2LlmConfig โ€” Configuration for code2llm analysis generation.
  • LLMConfig โ€” Configuration for optional LLM-assisted documentation generation.
  • Code2DocsConfig โ€” Main configuration for code2docs.
  • ApiChange โ€” A single API change between two analysis snapshots.
  • ApiChangelogGenerator โ€” Generate API changelog by diffing current analysis with a saved snapshot.
  • ReadmeGeneratorAdapter โ€” โ€”
  • ApiReferenceAdapter โ€” โ€”
  • ModuleDocsAdapter โ€” โ€”
  • ArchitectureAdapter โ€” โ€”
  • DepGraphAdapter โ€” โ€”
  • CoverageAdapter โ€” โ€”
  • ApiChangelogAdapter โ€” โ€”
  • ExamplesAdapter โ€” โ€”
  • MkDocsAdapter โ€” โ€”
  • GettingStartedAdapter โ€” โ€”
  • ConfigDocsAdapter โ€” โ€”
  • ContributingAdapter โ€” โ€”
  • Code2LlmAdapter โ€” Adapter for code2llm analysis generation.
  • ContributingGenerator โ€” Generate CONTRIBUTING.md by detecting dev tools from pyproject.toml.
  • ReadmeGenerator โ€” Generate README.md from AnalysisResult.
  • DocstringInfo โ€” Parsed docstring with sections.
  • DocstringExtractor โ€” Extract and parse docstrings from AnalysisResult.
  • Endpoint โ€” Represents a detected web endpoint.
  • EndpointDetector โ€” Detects web endpoints from decorator patterns in source code.
  • ArchitectureGenerator โ€” Generate docs/architecture.md โ€” architecture overview with diagrams.
  • ProjectScanner โ€” Wraps code2llm's ProjectAnalyzer with code2docs-specific defaults.
  • DefaultGroup โ€” Click Group that routes unknown subcommands to 'generate'.
  • DependencyInfo โ€” Information about a project dependency.
  • ProjectDependencies โ€” All detected project dependencies.
  • DependencyScanner โ€” Scan and parse project dependency files.

Functions

  • detect_changes_example(project_path) โ€” Detect what files have changed since last documentation generation.
  • update_docs_incrementally(project_path) โ€” Update only the parts of docs that need changing.
  • force_full_regeneration(project_path) โ€” Force full regeneration of all documentation.
  • watch_and_auto_regenerate(project_path, interval) โ€” Watch for file changes and auto-regenerate documentation.
  • custom_watcher_with_hooks(project_path) โ€” Set up a custom watcher with pre/post generation hooks.
  • sync_with_git_changes(project_path) โ€” Only regenerate docs for files changed in git.
  • generate_custom_report(project_path) โ€” Generate a custom metrics report.
  • markdown_formatting_examples() โ€” Demonstrate markdown formatting utilities.
  • generate_complex_document() โ€” Generate a complex markdown document using the formatter.
  • badge_examples() โ€” Generate various badge examples.
  • toc_examples() โ€” Demonstrate table of contents generation.
  • build_custom_readme() โ€” Build a custom README using formatters.
  • generate_readme_simple(project_path) โ€” Generate README.md content from a project.
  • generate_full_documentation(project_path) โ€” Generate complete documentation for a project.
  • custom_documentation_pipeline(project_path) โ€” Create a custom documentation pipeline.
  • inspect_project_structure(project_path) โ€” Inspect project structure from analysis.
  • generate_docs_if_needed(project_path, force) โ€” Only generate docs if code has changed.
  • detect_flask_endpoints(project_path) โ€” Detect Flask endpoints in a project.
  • detect_fastapi_endpoints(project_path) โ€” Detect FastAPI endpoints in a project.
  • generate_api_docs_from_endpoints(project_path, output_dir) โ€” Generate API documentation from detected endpoints.
  • create_example_web_apps(target_dir) โ€” Create example Flask and FastAPI apps for testing.
  • document_web_project(project_path) โ€” Complete workflow: detect endpoints and generate docs.
  • run_cli_basic(project_path) โ€” Run code2docs CLI programmatically.
  • run_cli_with_config(project_path, config_path) โ€” Run with custom configuration.
  • create_basic_config() โ€” Create a basic configuration.
  • create_advanced_config() โ€” Create advanced configuration with all options.
  • save_yaml_config_example(path) โ€” Save example YAML config to file.
  • load_config_from_yaml(path) โ€” Load configuration from YAML file.
  • start_watcher(project_path, config) โ€” Start watching project for file changes and auto-resync docs.
  • generate_badges(project_name, badge_types, stats, deps) โ€” Generate shields.io badge Markdown strings.
  • generate_toc(markdown_content, max_depth) โ€” Generate a table of contents from Markdown headings.
  • extract_headings(content, max_depth) โ€” Extract headings from Markdown content.
  • generate_docs(project_path, config) โ€” High-level function to generate all documentation.
  • generate_code2llm_analysis(project_path, config) โ€” Convenience function to generate code2llm analysis.
  • generate_readme(project_path, output, sections, sync_markers) โ€” Convenience function to generate a README.
  • analyze_and_document(project_path, config) โ€” Convenience function: analyze a project in one call.
  • main() โ€” code2docs โ€” Auto-generate project documentation from source code.
  • generate(project_path, config_path, readme_only, sections) โ€” Generate documentation (default command).
  • sync(project_path, config_path, verbose, dry_run) โ€” Synchronize documentation with source code changes.
  • watch(project_path, config_path, verbose) โ€” Watch for file changes and auto-regenerate docs.
  • init(project_path, output) โ€” Initialize code2docs.yaml configuration file.
  • check(project_path, config_path, target) โ€” Health check โ€” verify documentation completeness.
  • diff(project_path, config_path) โ€” Preview what would change without writing anything.

Project Structure

๐Ÿ“ฆ code2docs (1 functions) ๐Ÿ“„ code2docs.__main__ ๐Ÿ“ฆ code2docs.analyzers ๐Ÿ“„ code2docs.analyzers.dependency_scanner (6 functions, 3 classes) ๐Ÿ“„ code2docs.analyzers.docstring_extractor (10 functions, 2 classes) ๐Ÿ“„ code2docs.analyzers.endpoint_detector (3 functions, 2 classes) ๐Ÿ“„ code2docs.analyzers.project_scanner (4 functions, 1 classes) ๐Ÿ“„ code2docs.base (3 functions, 2 classes) ๐Ÿ“„ code2docs.cli (14 functions, 1 classes) ๐Ÿ“„ code2docs.config (5 functions, 7 classes) ๐Ÿ“„ code2docs.examples.advanced_usage ๐Ÿ“„ code2docs.examples.quickstart ๐Ÿ“ฆ code2docs.formatters ๐Ÿ“„ code2docs.formatters.badges (2 functions) ๐Ÿ“„ code2docs.formatters.markdown (13 functions, 1 classes) ๐Ÿ“„ code2docs.formatters.toc (3 functions) ๐Ÿ“ฆ code2docs.generators (1 functions) ๐Ÿ“„ code2docs.generators._registry_adapters (26 functions, 13 classes) ๐Ÿ“„ code2docs.generators._source_links (6 functions, 1 classes) ๐Ÿ“„ code2docs.generators.api_changelog_gen (9 functions, 2 classes) ๐Ÿ“„ code2docs.generators.api_reference_gen (7 functions, 1 classes) ๐Ÿ“„ code2docs.generators.architecture_gen (10 functions, 1 classes) ๐Ÿ“„ code2docs.generators.changelog_gen (6 functions, 2 classes) ๐Ÿ“„ code2docs.generators.code2llm_gen (5 functions, 1 classes) ๐Ÿ“„ code2docs.generators.config_docs_gen (4 functions, 1 classes) ๐Ÿ“„ code2docs.generators.contributing_gen (8 functions, 1 classes) ๐Ÿ“„ code2docs.generators.coverage_gen (7 functions, 1 classes) ๐Ÿ“„ code2docs.generators.depgraph_gen (9 functions, 1 classes) ๐Ÿ“„ code2docs.generators.examples_gen (14 functions, 1 classes) ๐Ÿ“„ code2docs.generators.getting_started_gen (8 functions, 1 classes) ๐Ÿ“„ code2docs.generators.mkdocs_gen (4 functions, 1 classes) ๐Ÿ“„ code2docs.generators.module_docs_gen (9 functions, 1 classes) ๐Ÿ“„ code2docs.generators.readme_gen (18 functions, 1 classes) ๐Ÿ“„ code2docs.llm_helper (7 functions, 1 classes) ๐Ÿ“„ code2docs.registry (4 functions, 1 classes) ๐Ÿ“ฆ code2docs.sync ๐Ÿ“„ code2docs.sync.differ (7 functions, 2 classes) ๐Ÿ“„ code2docs.sync.updater (2 functions, 1 classes) ๐Ÿ“„ code2docs.sync.watcher (1 functions) ๐Ÿ“„ examples.01_cli_usage (2 functions) ๐Ÿ“„ examples.02_configuration (4 functions) ๐Ÿ“„ examples.03_programmatic_api (5 functions) ๐Ÿ“„ examples.04_sync_and_watch (6 functions) ๐Ÿ“„ examples.05_custom_generators (13 functions, 3 classes) ๐Ÿ“„ examples.06_formatters (5 functions) ๐Ÿ“„ examples.07_web_frameworks (5 functions) ๐Ÿ“„ examples.basic_usage ๐Ÿ“„ examples.class_examples ๐Ÿ“„ examples.entry_points

Requirements

  • Python >= >=3.9
  • code2llm >=0.5.0- jinja2 >=3.1- click >=8.0- pyyaml >=6.0- rich >=13.0

Contributing

Contributors:

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/wronai/code2docs
cd code2docs

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

Documentation

Generated Files

Output Description Link
README.md Project overview (this file) โ€”
docs/api.md Consolidated API reference View
docs/modules.md Module reference with metrics View
docs/architecture.md Architecture with diagrams View
docs/dependency-graph.md Dependency graphs View
docs/coverage.md Docstring coverage report View
docs/getting-started.md Getting started guide View
docs/configuration.md Configuration reference View
docs/api-changelog.md API change tracking View
CONTRIBUTING.md Contribution guidelines View
examples/ Usage examples Browse
mkdocs.yml MkDocs configuration โ€” 

Content outside markers is preserved.

## Architecture

code2docs/ โ”œโ”€โ”€ cli.py # CLI (click-based) โ”œโ”€โ”€ config.py # Configuration (code2docs.yaml) โ”œโ”€โ”€ analyzers/ # Adapters to code2llm + custom detectors โ”‚ โ”œโ”€โ”€ project_scanner.py # Wrapper on code2llm.ProjectAnalyzer โ”‚ โ”œโ”€โ”€ endpoint_detector.py # Flask/FastAPI/Django route extraction โ”‚ โ”œโ”€โ”€ docstring_extractor.py โ”‚ โ””โ”€โ”€ dependency_scanner.py โ”œโ”€โ”€ generators/ # Documentation generators โ”‚ โ”œโ”€โ”€ readme_gen.py # README.md generator โ”‚ โ”œโ”€โ”€ api_reference_gen.py # docs/api/ reference from signatures โ”‚ โ”œโ”€โ”€ module_docs_gen.py # docs/modules/ per-module docs โ”‚ โ”œโ”€โ”€ examples_gen.py # examples/ from signatures โ”‚ โ”œโ”€โ”€ changelog_gen.py # CHANGELOG from git log โ”‚ โ””โ”€โ”€ architecture_gen.py # Architecture + Mermaid diagrams โ”œโ”€โ”€ templates/ # Jinja2 templates โ”œโ”€โ”€ sync/ # Change detection & selective regeneration โ”‚ โ”œโ”€โ”€ differ.py โ”‚ โ”œโ”€โ”€ updater.py โ”‚ โ””โ”€โ”€ watcher.py โ””โ”€โ”€ formatters/ # Markdown, badges, TOC


## Requirements

- Python >= 3.9
- [code2llm](https://github.com/wronai/code2llm) >= 0.5.0
- Jinja2 >= 3.1
- Click >= 8.0
- PyYAML >= 6.0

## License

Licensed under Apache-2.0.
## Author

Tom Sapletta

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for tom-sapletta-com from gravatar.com tom-sapletta-com

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License Expression: Apache-2.0
    SPDX License Expression
  • Author: Tom Sapletta
  • Tags documentation , auto-docs , readme-generator , api-reference , code-analysis , static-analysis , markdown
  • Requires: Python >=3.9
  • Provides-Extra: llm , git , watch , mkdocs , dev , all
Classifiers

Release history Release notifications | RSS feed

3.0.33

3.0.32

3.0.31

3.0.30

3.0.29

3.0.28

3.0.27

3.0.26

This version

3.0.25

3.0.24

3.0.23

3.0.22

3.0.21

3.0.20

3.0.19

3.0.18

3.0.17

3.0.16

3.0.15

3.0.14

3.0.13

3.0.12

3.0.11

3.0.10

3.0.9

3.0.8

3.0.7

3.0.6

3.0.5

3.0.4

3.0.3

3.0.2

2.1.93

0.2.11

0.2.10

0.2.2

0.2.1

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

code2docs-3.0.25.tar.gz (88.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

code2docs-3.0.25-py3-none-any.whl (88.1 kB view details)

Uploaded Python 3

File details

Details for the file code2docs-3.0.25.tar.gz.

File metadata

  • Download URL: code2docs-3.0.25.tar.gz
  • Upload date:
  • Size: 88.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for code2docs-3.0.25.tar.gz
Algorithm Hash digest
SHA256 a2ea5730456f031704af5cd9fa5a94ed05d1c1388e5fe466aecda30aea09c68f
MD5 7e1416b02364c5b1446286d8d3706fa6
BLAKE2b-256 9cf8a966431d339a85ecef80dfe39e7ca8a56cff14d7c9e92241fa06b9094f2d

See more details on using hashes here.

File details

Details for the file code2docs-3.0.25-py3-none-any.whl.

File metadata

  • Download URL: code2docs-3.0.25-py3-none-any.whl
  • Upload date:
  • Size: 88.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.13.7

File hashes

Hashes for code2docs-3.0.25-py3-none-any.whl
Algorithm Hash digest
SHA256 cff1b1a9d47526de64e1a8d642ff6c7f480e02f734f951417e30e1d5fcf7fbd5
MD5 b94e6b8ebe63a867503ebca2232b1006
BLAKE2b-256 1150addefb4a8ea4244de67000194828ce41c87d9e9c9a9c3d6a21356fd9c035

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page