rdocgen 0.1.0

Markdown documentation generator from python source code

rdocgen

rdocgen is an alternative to python documentation generators that use standard docstrings. It uses inline comments as the source of descriptions and exports documentation in markdown files compatible with SSG tools such as VitePress.

Write documentation like this:

def example_function(
    value: int,  # input integer
    label: Optional[str] = None,  # optional label
) -> str:

Generated VitePress documentation will look like:

Why?

• It is simpler than docstrings.
• It provides a single source of truth, so documentation drift is less likely.

Use this project only if you do not rely on standard docstring tooling.

Usage

Single file

rdocgen -c path/to/module.py -o ./out_docs

When -c points to a single file, rdocgen writes a single output file (index.md by default) with all content for that file.

Directory

rdocgen -c path/to/package -o ./out_docs

Include / exclude files

rdocgen -c src -o ./out_docs \
  --include-path "rdocgen/**" \
  --exclude-path "**/tests/**"

Control hierarchy and output

rdocgen -c src -o ./out_docs \
  --module-depth 2 \
  --project-name "My SDK" \
  --flatten \
  --index-title "API"

Visibility and types

rdocgen -c src -o ./out_docs \
  --include-private \
  --include-dunder \
  --include-types class,function

Docstring rendering

rdocgen -c src -o ./out_docs \
  --docstring-style python-fences \
  --code-fence-language python \
  --code-fence-suffix "copy showLineNumbers"

CLI flags (high level)

• --code / -c: File or directory to parse.
• --outdir / -o: Output directory.
• --include-path / --exclude-path: Glob filters (repeatable).
• --module-depth: Grouping depth (1, 2, or all).
• --project-name: Override the project name shown in indexes.
• --clean / --no-clean: Control output dir deletion (default is no deletion).
• --force: Allow deleting protected directories like .git.
• --dry-run: Print planned actions without writing files.
• --include-private / --include-dunder: Include hidden members.
• --include-types / --exclude-types: Filter by class,function,enum,attribute.
• --sort: source-order or alpha.
• --flatten: Emit a single output file.
• --index-title: Override root index title.
• --docstring-style: raw, python-fences, or preserve.
• --code-fence-language: Default language for unlabeled fences.
• --code-fence-suffix: Extra tokens for opening fences (e.g., copy showLineNumbers).
• --output-extension: Override .md/.mdx.
• --fail-on-parse-error: Abort on invalid Python files.

Notes

• --clean deletes the contents of the output directory, not the directory itself.
• Without --force, cleanup is blocked if the output dir contains hidden files, symlinks, or files that are not .md/.mdx.
• This project only reads source files; it does not execute code.