Module

autodoc.extractors.cli

CLI documentation extractor for autodoc system.

Extracts documentation from command-line applications built with Click, argparse, or Typer.

View source
1 Class 2 Functions

Classes

CLIExtractor
Extract CLI documentation from Click/argparse/typer applications. This extractor introspects CLI f…
13

Extract CLI documentation from Click/argparse/typer applications.

This extractor introspects CLI frameworks to build comprehensive documentation for commands, options, arguments, and their relationships.

Currently supported frameworks:

  • Click (full support)
  • argparse (planned)
  • Typer (planned)
Inherits from Extractor

Methods 3

extract
Extract documentation from CLI application.
1 list[DocElement] 
def extract(self, source: Any) -> list[DocElement]

Extract documentation from CLI application.

Parameters 1
source Any

CLI application object - For Click: click.Group or click.Command - For argparse: ArgumentParser instance - For Typer: Typer app instance
Returns

list[DocElement] —

List of DocElements representing the CLI structure

get_template_dir
Get the template directory name for this extractor.
0 str 
def get_template_dir(self) -> str

Get the template directory name for this extractor.

Returns

str —

Template directory name (e.g., 'cli', 'python', 'openapi')

get_output_path
Determine output path for CLI element.
1 Path 
def get_output_path(self, element: DocElement) -> Path

Determine output path for CLI element.

Parameters 1
element DocElement

CLI DocElement
Returns

Path —

Relative path for the generated markdown file

Internal Methods 10
__init__
Initialize CLI extractor.
2 None 
def __init__(self, framework: str = 'click', include_hidden: bool = False)

Initialize CLI extractor.

Parameters 2
framework str

CLI framework to extract from ('click', 'argparse', 'typer')
include_hidden bool

Include hidden commands (default: False)
_extract_from_click
Extract documentation from Click command group.
1 list[DocElement] 
def _extract_from_click(self, cli: click.Group) -> list[DocElement]

Extract documentation from Click command group.

Parameters 1
cli click.Group

Click Group or Command instance
Returns

list[DocElement] —

List containing the main CLI element and all subcommands as separate pages

_extract_click_group
Extract Click command group documentation.
2 DocElement 
def _extract_click_group(self, group: click.Group, parent_name: str | None = None) -> DocElement

Extract Click command group documentation.

Parameters 2
group click.Group

Click Group instance
parent_name str | None

Parent command name for nested groups
Returns

DocElement —

DocElement representing the command group

_extract_click_command
Extract Click command documentation.
2 DocElement 
def _extract_click_command(self, cmd: click.Command, parent_name: str | None = None) -> DocElement

Extract Click command documentation.

Parameters 2
cmd click.Command

Click Command instance
parent_name str | None

Parent group name
Returns

DocElement —

DocElement representing the command

_extract_click_parameter
Extract Click parameter (option or argument) documentation.
2 DocElement 
def _extract_click_parameter(self, param: click.Parameter, parent_name: str) -> DocElement

Extract Click parameter (option or argument) documentation.

Parameters 2
param click.Parameter

Click Parameter instance
parent_name str

Parent command qualified name
Returns

DocElement —

DocElement representing the parameter

_strip_examples_from_description
Remove example blocks from docstring description.
1 str 
def _strip_examples_from_description(self, docstring: str) -> str

Remove example blocks from docstring description.

Parameters 1
docstring str

Full docstring
Returns

str —

Description without Examples section

_extract_examples_from_docstring
Extract example blocks from docstring.
1 list[str] 
def _extract_examples_from_docstring(self, docstring: str) -> list[str]

Extract example blocks from docstring.

Parameters 1
docstring str

Function or command docstring
Returns

list[str] —

List of example code blocks

_extract_from_argparse
Extract documentation from argparse ArgumentParser.
1 list[DocElement] 
def _extract_from_argparse(self, parser: Any) -> list[DocElement]

Extract documentation from argparse ArgumentParser.

Parameters 1
parser Any

ArgumentParser instance
Returns

list[DocElement] —

List of DocElements

_extract_from_typer
Extract documentation from Typer app. Typer is built on top of Click, so we ca…
1 list[DocElement] 
def _extract_from_typer(self, app: Any) -> list[DocElement]

Extract documentation from Typer app.

Typer is built on top of Click, so we can leverage the existing Click extraction logic. Typer apps expose their underlying Click structure through various methods.

Parameters 1
app Any

Typer app instance
Returns

list[DocElement] —

List of DocElements

_typer_to_click_group
Helper to convert a Typer app to a Click group recursively.
1 Any 
def _typer_to_click_group(self, typer_app: Any) -> Any

Helper to convert a Typer app to a Click group recursively.

Parameters 1
typer_app Any

Typer app instance
Returns

Any —

Click group or None

Functions

_is_sentinel_value
Check if a value is a Click sentinel (like UNSET). Click uses sentinel objects to distinguish betw…
1 bool 
def _is_sentinel_value(value: Any) -> bool

Check if a value is a Click sentinel (like UNSET).

Click uses sentinel objects to distinguish between "not provided" and None. These should not appear in user-facing documentation.

Parameters 1

Name Type Default Description
value Any —

Value to check

Returns

bool —

True if value is a sentinel that should be filtered

_format_default_value
Format a default value for display, filtering sentinel values.
1 str | None 
def _format_default_value(value: Any) -> str | None

Format a default value for display, filtering sentinel values.

Parameters 1

Name Type Default Description
value Any —

The default value to format

Returns

str | None —

Formatted string or None if value should not be displayed