API.md

API Documentation — doc-gen

Auto-generated by doc-gen from 4 source files.

Module: src/doc_gen/__init__.py

doc-gen: Project Documentation Generator.

Generate README files, API documentation, project trees, and dependency graphs from any Python project using only the standard library.

run_cli() -> None

Entry point: dispatch to CLI or TUI based on --tui.

run_tui() -> None

Launch the curses-based TUI.

Module: src/doc_gen/__main__.py

python -m doc_gen entry point.

main() -> None

Delegate to the CLI entry point.

Module: src/doc_gen/cli.py

class FileInfo

Lightweight metadata about a file in the project.

class FunctionDoc

class ClassDoc

class ModuleDoc

_c(code: str, text: str) -> str

Wrap text in ANSI colour code unless colour is disabled.

_heading(text: str) -> str

_ok(text: str) -> str

_warn(text: str) -> str

_path(text: str) -> str

_highlight(text: str) -> str

_walk_project(root: Path, max_depth: int=8) -> list[FileInfo]

Walk root and return a list of FileInfo entries (files only).

_count_lines(path: Path) -> int

Return number of lines in a text file (fast approximate).

_find_python_files(root: Path) -> list[Path]

Return all .py files under root, skipping excluded dirs.

_safe_read(path: Path) -> str

Read file as UTF-8, falling back to latin-1.

_format_size(size: int) -> str

Human-readable file size.

_plural(n: int, word: str, plural: str ? None=None) -> str

_detect_project_name(root: Path) -> str

Heuristic: pyproject.toml name, then directory name.

_detect_project_version(root: Path) -> str

Heuristic for version from pyproject.toml.

_detect_project_desc(root: Path) -> str

Heuristic for description from pyproject.toml.

_module_summary(path: Path, root: Path) -> str

Return the first-line docstring of a module, if any.

cmd_readme(args: argparse.Namespace) -> None

Generate a README.md for the project at args.directory.

_parse_node(node: ast.AST) -> str

Best-effort reconstruction of a source-code snippet for a node.

_format_function_arg(arg: ast.arg) -> str

Format a single function argument with annotation.

_format_function_args(args: ast.arguments) -> str

Reconstruct human-readable argument signature.

_extract_decorators(decs: list[ast.expr]) -> list[str]

_parse_function(node: ast.FunctionDef) -> FunctionDoc

_parse_class(node: ast.ClassDef) -> ClassDoc

_parse_module(path: Path) -> ModuleDoc ? None

Parse a single Python file into a ModuleDoc.

_render_api_text(mod: ModuleDoc, root: Path) -> Iterator[str]

Yield Markdown lines for a single module's API docs.

cmd_api(args: argparse.Namespace) -> None

Generate API documentation for args.directory.

_render_tree_lines(root: Path, files: list[FileInfo]) -> list[str]

Return lines for an ASCII project tree.

cmd_tree(args: argparse.Namespace) -> None

Print a project tree with file sizes and line counts.

_extract_imports(code: str) -> Iterator[tuple[(str, str, int)]]

Yield (module_name, alias_or_name, lineno) for each import.

_categorise_import(module: str, local_top_levels: set[str]) -> str

Return one of 'stdlib', 'third-party', 'local'.

cmd_deps(args: argparse.Namespace) -> None

Print a dependency report for args.directory.

build_parser() -> argparse.ArgumentParser

Build the top-level argument parser.

main() -> None

Top-level entry point: parse args, dispatch.

Module: src/doc_gen/tui.py

class TextBuffer

A scrollable text buffer rendered into a curses window.

__init__(self, lines: list[str]) -> None

render(self, win: Any, top: int, left: int, height: int, width: int) -> None

Paint visible region of the buffer.

scroll_up(self, n: int=1) -> None

scroll_down(self, n: int=1) -> None

page_up(self) -> None

page_down(self) -> None

home(self) -> None

end(self) -> None

_add_colored(win: Any, y: int, x: int, text: str) -> None _ @staticmethod_

Write text at (y, x) with simple ANSI-like colour markup.

Markers: @G@text@@ = green, @Y@text@@ = yellow, @C@text@@ = cyan, @M@text@@ = magenta, @B@text@@ = blue/bold, @D@text@@ = dim, @@ = reset.

_init_colors() -> None

Initialise curses colour pairs if the terminal supports colour.

_show_menu(win: Any, title: str, items: list[str], selected: int) -> None

Render a menu in window win.

_show_prompt(win: Any, prompt: str) -> str ? None

Show a one-line text input prompt. Returns the entered string or None on cancel.

_display_result(stdscr: Any, title: str, lines: list[str]) -> None

Show a scrollable result in a full-screen overlay.

_action_tree(stdscr: Any, path_str: str) -> None

Show project tree.

_action_api(stdscr: Any, path_str: str) -> None

Show API docs.

_action_readme(stdscr: Any, path_str: str) -> None

Show and optionally write README.

_action_deps(stdscr: Any, path_str: str) -> None

Show dependency report.

tui_main(stdscr: Any ? None=None) -> None

Launch the curses TUI. If stdscr is None, we call curses.wrapper().

_run_tui(stdscr: Any) -> None

Internal TUI runner — receives a curses window.