Skip to content

api.md

Latest commit

 

History

History
635 lines (443 loc) · 37.5 KB

api.md

File metadata and controls

635 lines (443 loc) · 37.5 KB

code2docs — API Reference

40 modules | 255 functions | 56 classes

Contents

Core

analyzers source

Class Methods Description Source
DependencyInfo 0 Information about a project dependency. source
DependencyScanner 1 Scan and parse project dependency files. source
ProjectDependencies 0 All detected project dependencies. source
DocstringExtractor 3 Extract and parse docstrings from AnalysisResult. source
DocstringInfo 0 Parsed docstring with sections. source
Endpoint 0 Represents a detected web endpoint. source
EndpointDetector 1 Detects web endpoints from decorator patterns in source code. source
ProjectScanner 1 Wraps code2llm's ProjectAnalyzer with code2docs-specific defaults. source

DocstringExtractor methods:

  • extract_all(result) — Extract docstrings for all functions and classes.
  • parse(docstring) — Parse a docstring into structured sections (orchestrator).
  • coverage_report(result) — Calculate docstring coverage statistics.
Function Signature CC Description Source
analyze_and_document analyze_and_document(project_path, config) 1 Convenience function: analyze a project in one call. source

base source

Class Methods Description Source
BaseGenerator 2 Abstract base for all documentation generators. source
GenerateContext 0 Shared context passed to all generators during a run. source

BaseGenerator methods:

  • should_run() — Return True if this generator should execute.
  • run(ctx) — Execute generation and write output.

cli source

Class Methods Description Source
DefaultGroup 1 Click Group that routes unknown subcommands to 'generate'. source
Function Signature CC Description Source
check check(project_path, config_path, target) 1 Health check — verify documentation completeness. source
diff diff(project_path, config_path) 1 Preview what would change without writing anything. source
generate generate(project_path, config_path, readme_only, sections, ...) 7 Generate documentation (default command). source
init init(project_path, output) 1 Initialize code2docs.yaml configuration file. source
main main() 1 code2docs — Auto-generate project documentation from source code. source
sync sync(project_path, config_path, verbose, dry_run) 2 Synchronize documentation with source code changes. source
watch watch(project_path, config_path, verbose) 2 Watch for file changes and auto-regenerate docs. source

config source

Class Methods Description Source
Code2DocsConfig 2 Main configuration for code2docs. source
Code2LlmConfig 0 Configuration for code2llm analysis generation. source
DocsConfig 0 Configuration for docs/ generation. source
ExamplesConfig 0 Configuration for examples/ generation. source
LLMConfig 1 Configuration for optional LLM-assisted documentation generation. source
ReadmeConfig 0 Configuration for README generation. source
SyncConfig 0 Configuration for synchronization. source

Code2DocsConfig methods:

  • from_yaml(cls, path) — Load configuration from code2docs.yaml.
  • to_yaml(path) — Save configuration to YAML file.

formatters source

Class Methods Description Source
MarkdownFormatter 12 Helper for constructing Markdown documents. source

MarkdownFormatter methods:

  • heading(text, level) — Add a heading.
  • paragraph(text) — Add a paragraph.
  • blockquote(text) — Add a blockquote.
  • code_block(code, language) — Add a fenced code block.
  • inline_code(text) — Return inline code string.
  • bold(text) — Return bold string.
  • link(text, url) — Return a Markdown link.
  • list_item(text, indent) — Add a list item.
  • table(headers, rows) — Add a Markdown table.
  • separator() — Add a horizontal rule.
  • blank() — Add a blank line.
  • render() — Render accumulated Markdown to string.
Function Signature CC Description Source
generate_badges generate_badges(project_name, badge_types, stats, deps) 4 Generate shields.io badge Markdown strings. source
extract_headings extract_headings(content, max_depth) 6 Extract headings from Markdown content. source
generate_toc generate_toc(markdown_content, max_depth) 3 Generate a table of contents from Markdown headings. source

generators source

Class Methods Description Source
ApiChangelogAdapter 2 — source
ApiReferenceAdapter 2 — source
ArchitectureAdapter 2 — source
Code2LlmAdapter 2 Adapter for code2llm analysis generation. source
ConfigDocsAdapter 2 — source
ContributingAdapter 2 — source
CoverageAdapter 2 — source
DepGraphAdapter 2 — source
ExamplesAdapter 2 — source
GettingStartedAdapter 2 — source
MkDocsAdapter 2 — source
ModuleDocsAdapter 2 — source
OrgReadmeAdapter 2 Adapter for organization README generation. source
ReadmeGeneratorAdapter 2 — source
SourceLinker 2 Build source-code links (relative paths + optional GitHub/GitLab URLs). source
ApiChange 1 A single API change between two analysis snapshots. source
ApiChangelogGenerator 2 Generate API changelog by diffing current analysis with a saved snapshot. source
ApiReferenceGenerator 1 Generate docs/api.md — consolidated API reference. source
ArchitectureGenerator 1 Generate docs/architecture.md — architecture overview with diagrams. source
ChangelogEntry 0 A single changelog entry. source
ChangelogGenerator 1 Generate CHANGELOG.md from git log and analysis diff. source
Code2LlmGenerator 2 Generate code2llm analysis files in project/ directory. source
ConfigDocsGenerator 1 Generate docs/configuration.md from Code2DocsConfig dataclass. source
ContributingGenerator 1 Generate CONTRIBUTING.md by detecting dev tools from pyproject.toml. source
CoverageGenerator 1 Generate docs/coverage.md — docstring coverage report. source
DepGraphGenerator 1 Generate docs/dependency-graph.md with Mermaid diagrams. source
ExamplesGenerator 2 Generate examples/ — usage examples from public API signatures. source
GettingStartedGenerator 1 Generate docs/getting-started.md from entry points and dependencies. source
MkDocsGenerator 2 Generate mkdocs.yml from the docs/ directory structure. source
ModuleDocsGenerator 1 Generate docs/modules.md — consolidated module documentation. source
OrgReadmeGenerator 2 Generate organization README with list of projects and brief descriptions. source
ReadmeGenerator 2 Generate README.md from AnalysisResult. source

ApiChangelogAdapter methods:

  • should_run()
  • run(ctx)

ApiReferenceAdapter methods:

  • should_run()
  • run(ctx)

ArchitectureAdapter methods:

  • should_run()
  • run(ctx)

Code2LlmAdapter methods:

  • should_run()
  • run(ctx)

ConfigDocsAdapter methods:

  • should_run()
  • run(ctx)

ContributingAdapter methods:

  • should_run()
  • run(ctx)

CoverageAdapter methods:

  • should_run()
  • run(ctx)

DepGraphAdapter methods:

  • should_run()
  • run(ctx)

ExamplesAdapter methods:

  • should_run()
  • run(ctx)

GettingStartedAdapter methods:

  • should_run()
  • run(ctx)

MkDocsAdapter methods:

  • should_run()
  • run(ctx)

ModuleDocsAdapter methods:

  • should_run()
  • run(ctx)

OrgReadmeAdapter methods:

  • should_run()
  • run(ctx)

ReadmeGeneratorAdapter methods:

  • should_run()
  • run(ctx)

SourceLinker methods:

  • source_link(file, line) — Return a Markdown link to source, or empty string if unavailable.
  • file_link(file) — Return a Markdown link to a file (no line number).

ApiChangelogGenerator methods:

  • generate(project_path) — Generate api-changelog.md by comparing with previous snapshot.
  • save_snapshot(project_path) — Save current API state as snapshot for future diffs.

Code2LlmGenerator methods:

  • generate_all() — Generate all code2llm analysis files.
  • get_analysis_summary() — Get a summary of the analysis for integration with other docs.

ExamplesGenerator methods:

  • generate_all() — Generate all example files. Returns {filename: content}.
  • write_all(output_dir, files) — Write all generated example files.

MkDocsGenerator methods:

  • generate(docs_dir) — Generate mkdocs.yml content.
  • write(output_path, content) — Write mkdocs.yml file.

OrgReadmeGenerator methods:

  • generate() — Generate organization README content.
  • write(output_path, content) — Write README to output path.

ReadmeGenerator methods:

  • generate() — Generate full README content.
  • write(path, content) — Write README, respecting sync markers if existing file has them.
Function Signature CC Description Source
generate_code2llm_analysis generate_code2llm_analysis(project_path, config) 2 Convenience function to generate code2llm analysis. source
parse_gitignore parse_gitignore(project_path) 15 ⚠️ Parse .gitignore file and return list of patterns to exclude. source
generate_docs generate_docs(project_path, config) 5 High-level function to generate all documentation. source
generate_readme generate_readme(project_path, output, sections, sync_markers, ...) 3 Convenience function to generate a README. source

llm_helper source

Class Methods Description Source
LLMHelper 6 Thin wrapper around litellm for documentation generation. source

LLMHelper methods:

  • complete(prompt, system) — Send a completion request. Returns None on any failure.
  • generate_project_description(project_name, modules_summary, entry_points) — Generate a concise project description from analysis data.
  • generate_architecture_summary(project_name, layers, patterns, metrics) — Generate a natural-language architecture overview.
  • generate_getting_started_summary(project_name, cli_commands, public_api) — Generate a getting-started introduction.
  • enhance_module_docstring(module_name, functions, classes) — Generate a module-level summary from its contents.

registry source

Class Methods Description Source
GeneratorRegistry 3 Registry of documentation generators. source

GeneratorRegistry methods:

  • add(generator) — Add a generator instance to the registry.
  • run_all(ctx) — Run every registered generator that should execute.
  • run_only(name, ctx) — Run a single generator by name.

sync source

Class Methods Description Source
ChangeInfo 0 Describes a detected change. source
Differ 2 Detect changes between current source and previous state. source
Updater 1 Apply selective documentation updates based on detected changes. source

Differ methods:

  • detect_changes(project_path) — Compare current file hashes with saved state. Return list of changes.
  • save_state(project_path) — Save current file hashes as state.
Function Signature CC Description Source
start_watcher start_watcher(project_path, config) 5 Start watching project for file changes and auto-resync docs. source

analyzers

analyzers.dependency_scanner source

Class Methods Description Source
DependencyInfo 0 Information about a project dependency. source
DependencyScanner 1 Scan and parse project dependency files. source
ProjectDependencies 0 All detected project dependencies. source

analyzers.docstring_extractor source

Class Methods Description Source
DocstringExtractor 3 Extract and parse docstrings from AnalysisResult. source
DocstringInfo 0 Parsed docstring with sections. source

DocstringExtractor methods:

  • extract_all(result) — Extract docstrings for all functions and classes.
  • parse(docstring) — Parse a docstring into structured sections (orchestrator).
  • coverage_report(result) — Calculate docstring coverage statistics.

analyzers.endpoint_detector source

Class Methods Description Source
Endpoint 0 Represents a detected web endpoint. source
EndpointDetector 1 Detects web endpoints from decorator patterns in source code. source

analyzers.project_scanner source

Class Methods Description Source
ProjectScanner 1 Wraps code2llm's ProjectAnalyzer with code2docs-specific defaults. source
Function Signature CC Description Source
analyze_and_document analyze_and_document(project_path, config) 1 Convenience function: analyze a project in one call. source

formatters

formatters.badges source

Function Signature CC Description Source
generate_badges generate_badges(project_name, badge_types, stats, deps) 4 Generate shields.io badge Markdown strings. source

formatters.markdown source

Class Methods Description Source
MarkdownFormatter 12 Helper for constructing Markdown documents. source

MarkdownFormatter methods:

  • heading(text, level) — Add a heading.
  • paragraph(text) — Add a paragraph.
  • blockquote(text) — Add a blockquote.
  • code_block(code, language) — Add a fenced code block.
  • inline_code(text) — Return inline code string.
  • bold(text) — Return bold string.
  • link(text, url) — Return a Markdown link.
  • list_item(text, indent) — Add a list item.
  • table(headers, rows) — Add a Markdown table.
  • separator() — Add a horizontal rule.
  • blank() — Add a blank line.
  • render() — Render accumulated Markdown to string.

formatters.toc source

Function Signature CC Description Source
extract_headings extract_headings(content, max_depth) 6 Extract headings from Markdown content. source
generate_toc generate_toc(markdown_content, max_depth) 3 Generate a table of contents from Markdown headings. source

generators

generators._registry_adapters source

Class Methods Description Source
ApiChangelogAdapter 2 — source
ApiReferenceAdapter 2 — source
ArchitectureAdapter 2 — source
Code2LlmAdapter 2 Adapter for code2llm analysis generation. source
ConfigDocsAdapter 2 — source
ContributingAdapter 2 — source
CoverageAdapter 2 — source
DepGraphAdapter 2 — source
ExamplesAdapter 2 — source
GettingStartedAdapter 2 — source
MkDocsAdapter 2 — source
ModuleDocsAdapter 2 — source
OrgReadmeAdapter 2 Adapter for organization README generation. source
ReadmeGeneratorAdapter 2 — source

ApiChangelogAdapter methods:

  • should_run()
  • run(ctx)

ApiReferenceAdapter methods:

  • should_run()
  • run(ctx)

ArchitectureAdapter methods:

  • should_run()
  • run(ctx)

Code2LlmAdapter methods:

  • should_run()
  • run(ctx)

ConfigDocsAdapter methods:

  • should_run()
  • run(ctx)

ContributingAdapter methods:

  • should_run()
  • run(ctx)

CoverageAdapter methods:

  • should_run()
  • run(ctx)

DepGraphAdapter methods:

  • should_run()
  • run(ctx)

ExamplesAdapter methods:

  • should_run()
  • run(ctx)

GettingStartedAdapter methods:

  • should_run()
  • run(ctx)

MkDocsAdapter methods:

  • should_run()
  • run(ctx)

ModuleDocsAdapter methods:

  • should_run()
  • run(ctx)

OrgReadmeAdapter methods:

  • should_run()
  • run(ctx)

ReadmeGeneratorAdapter methods:

  • should_run()
  • run(ctx)

generators._source_links source

Class Methods Description Source
SourceLinker 2 Build source-code links (relative paths + optional GitHub/GitLab URLs). source

SourceLinker methods:

  • source_link(file, line) — Return a Markdown link to source, or empty string if unavailable.
  • file_link(file) — Return a Markdown link to a file (no line number).

generators.api_changelog_gen source

Class Methods Description Source
ApiChange 1 A single API change between two analysis snapshots. source
ApiChangelogGenerator 2 Generate API changelog by diffing current analysis with a saved snapshot. source

ApiChangelogGenerator methods:

  • generate(project_path) — Generate api-changelog.md by comparing with previous snapshot.
  • save_snapshot(project_path) — Save current API state as snapshot for future diffs.

generators.api_reference_gen source

Class Methods Description Source
ApiReferenceGenerator 1 Generate docs/api.md — consolidated API reference. source

generators.architecture_gen source

Class Methods Description Source
ArchitectureGenerator 1 Generate docs/architecture.md — architecture overview with diagrams. source

generators.changelog_gen source

Class Methods Description Source
ChangelogEntry 0 A single changelog entry. source
ChangelogGenerator 1 Generate CHANGELOG.md from git log and analysis diff. source

generators.code2llm_gen source

Class Methods Description Source
Code2LlmGenerator 2 Generate code2llm analysis files in project/ directory. source

Code2LlmGenerator methods:

  • generate_all() — Generate all code2llm analysis files.
  • get_analysis_summary() — Get a summary of the analysis for integration with other docs.
Function Signature CC Description Source
generate_code2llm_analysis generate_code2llm_analysis(project_path, config) 2 Convenience function to generate code2llm analysis. source
parse_gitignore parse_gitignore(project_path) 15 ⚠️ Parse .gitignore file and return list of patterns to exclude. source

generators.config_docs_gen source

Class Methods Description Source
ConfigDocsGenerator 1 Generate docs/configuration.md from Code2DocsConfig dataclass. source

generators.contributing_gen source

Class Methods Description Source
ContributingGenerator 1 Generate CONTRIBUTING.md by detecting dev tools from pyproject.toml. source

generators.coverage_gen source

Class Methods Description Source
CoverageGenerator 1 Generate docs/coverage.md — docstring coverage report. source

generators.depgraph_gen source

Class Methods Description Source
DepGraphGenerator 1 Generate docs/dependency-graph.md with Mermaid diagrams. source

generators.examples_gen source

Class Methods Description Source
ExamplesGenerator 2 Generate examples/ — usage examples from public API signatures. source

ExamplesGenerator methods:

  • generate_all() — Generate all example files. Returns {filename: content}.
  • write_all(output_dir, files) — Write all generated example files.

generators.getting_started_gen source

Class Methods Description Source
GettingStartedGenerator 1 Generate docs/getting-started.md from entry points and dependencies. source

generators.mkdocs_gen source

Class Methods Description Source
MkDocsGenerator 2 Generate mkdocs.yml from the docs/ directory structure. source

MkDocsGenerator methods:

  • generate(docs_dir) — Generate mkdocs.yml content.
  • write(output_path, content) — Write mkdocs.yml file.

generators.module_docs_gen source

Class Methods Description Source
ModuleDocsGenerator 1 Generate docs/modules.md — consolidated module documentation. source

generators.org_readme_gen source

Class Methods Description Source
OrgReadmeGenerator 2 Generate organization README with list of projects and brief descriptions. source

OrgReadmeGenerator methods:

  • generate() — Generate organization README content.
  • write(output_path, content) — Write README to output path.

generators.readme_gen source

Class Methods Description Source
ReadmeGenerator 2 Generate README.md from AnalysisResult. source

ReadmeGenerator methods:

  • generate() — Generate full README content.
  • write(path, content) — Write README, respecting sync markers if existing file has them.
Function Signature CC Description Source
generate_readme generate_readme(project_path, output, sections, sync_markers, ...) 3 Convenience function to generate a README. source

sync

sync.differ source

Class Methods Description Source
ChangeInfo 0 Describes a detected change. source
Differ 2 Detect changes between current source and previous state. source

Differ methods:

  • detect_changes(project_path) — Compare current file hashes with saved state. Return list of changes.
  • save_state(project_path) — Save current file hashes as state.

sync.updater source

Class Methods Description Source
Updater 1 Apply selective documentation updates based on detected changes. source

sync.watcher source

Function Signature CC Description Source
start_watcher start_watcher(project_path, config) 5 Start watching project for file changes and auto-resync docs. source