Skip to content

API documentation

Complete API reference for Griffonner’s Python modules.

Core modules

griffonner.core

Main generation functionality.

Main generation logic for Griffonner.

Classes:

Functions:

  • categorise_files –

    Categorise files into frontmatter files and passthrough files.

  • copy_file_passthrough –

    Copy a file from source to output preserving directory structure.

  • find_all_files –

    Find all files in a directory recursively, excluding ignored patterns.

  • generate –

    Generate documentation from a file or directory.

  • generate_directory –

    Generate documentation from all files in a directory.

  • generate_file –

    Generate documentation files from a source file with frontmatter.

GenerationError

Bases: Exception

Base exception for generation errors.

categorise_files 

categorise_files(files: List[Path]) -> Tuple[List[Path], List[Path]]

Categorise files into frontmatter files and passthrough files.

Parameters:

  • files

    (List[Path]) –

    List of file paths to categorise

Returns:

copy_file_passthrough 

copy_file_passthrough(source_file: Path, source_dir: Path, output_dir: Path) -> Path

Copy a file from source to output preserving directory structure.

Parameters:

  • source_file

    (Path) –

    Source file path

  • source_dir

    (Path) –

    Base source directory

  • output_dir

    (Path) –

    Base output directory

Returns:

  • Path –

    Path to the copied output file

Raises:

find_all_files 

find_all_files(directory: Path, ignore_patterns: Optional[List[str]] = None) -> List[Path]

Find all files in a directory recursively, excluding ignored patterns.

Parameters:

  • directory

    (Path) –

    Directory to search

  • ignore_patterns

    (Optional[List[str]], default: None ) –

    Glob patterns to ignore

Returns:

  • List[Path] –

    List of all file paths not matching ignore patterns

Raises:

generate 

generate(source: Path, output_dir: Path, template_dirs: Optional[List[Path]] = None, plugin_manager: Optional[PluginManager] = None, ignore_patterns: Optional[List[str]] = None, default_griffe_config: Optional[Dict[str, Any]] = None) -> List[Path]

Generate documentation from a file or directory.

Parameters:

  • source

    (Path) –

    Source file or directory path

  • output_dir

    (Path) –

    Output directory path

  • template_dirs

    (Optional[List[Path]], default: None ) –

    Additional template search directories

  • plugin_manager

    (Optional[PluginManager], default: None ) –

    Optional plugin manager for processors/filters

  • ignore_patterns

    (Optional[List[str]], default: None ) –

    Glob patterns to ignore

  • default_griffe_config

    (Optional[Dict[str, Any]], default: None ) –

    Default Griffe configuration to merge with frontmatter

Returns:

  • List[Path] –

    List of generated output file paths

Raises:

generate_directory 

generate_directory(pages_dir: Path, output_dir: Path, template_dirs: Optional[List[Path]] = None, plugin_manager: Optional[PluginManager] = None, ignore_patterns: Optional[List[str]] = None, default_griffe_config: Optional[Dict[str, Any]] = None) -> List[Path]

Generate documentation from all files in a directory.

Parameters:

  • pages_dir

    (Path) –

    Directory containing source files (with or without frontmatter)

  • output_dir

    (Path) –

    Base output directory

  • template_dirs

    (Optional[List[Path]], default: None ) –

    Additional template search directories

  • plugin_manager

    (Optional[PluginManager], default: None ) –

    Optional plugin manager for processors/filters

  • ignore_patterns

    (Optional[List[str]], default: None ) –

    Glob patterns to ignore

  • default_griffe_config

    (Optional[Dict[str, Any]], default: None ) –

    Default Griffe configuration to merge with frontmatter

Returns:

  • List[Path] –

    List of all generated and copied output file paths

Raises:

generate_file 

generate_file(source_file: Path, source_dir: Path, output_dir: Path, template_dirs: Optional[List[Path]] = None, plugin_manager: Optional[PluginManager] = None, default_griffe_config: Optional[Dict[str, Any]] = None) -> List[Path]

Generate documentation files from a source file with frontmatter.

Parameters:

  • source_file

    (Path) –

    Path to source file with frontmatter

  • source_dir

    (Path) –

    Base source directory for calculating relative paths

  • output_dir

    (Path) –

    Base output directory

  • template_dirs

    (Optional[List[Path]], default: None ) –

    Additional template search directories

  • plugin_manager

    (Optional[PluginManager], default: None ) –

    Optional plugin manager for processors/filters

  • default_griffe_config

    (Optional[Dict[str, Any]], default: None ) –

    Default Griffe configuration to merge with frontmatter

Returns:

  • List[Path] –

    List of generated output file paths

Raises:

griffonner.cli

Command-line interface implementation.

Typer-based CLI for Griffonner.

Functions:

  • bundle_info_cmd –

    Show detailed information about a specific bundle.

  • generate_cmd –

    Generate documentation from source files with frontmatter.

  • main –

    Main entry point for the CLI.

  • main_callback –

    Main callback to handle global options.

  • plugins_cmd –

    List all available plugins (processors, filters, bundles).

  • setup_logging –

    Set up logging configuration.

  • templates –

    List available templates.

  • validate –

    Validate template syntax and structure.

  • version_callback –

    Print version and exit if –version is provided.

  • watch –

    Watch source directory for changes and regenerate documentation.

bundle_info_cmd 

bundle_info_cmd(bundle_name: Annotated[str, Argument(help='Bundle name to inspect')], verbose: Annotated[Optional[bool], Option(--verbose, -v, help='Enable verbose output')] = None) -> None

Show detailed information about a specific bundle.

Configuration is loaded from griffonner.yml/griffonner.yaml or pyproject.toml for verbose setting.

generate_cmd 

generate_cmd(source: Annotated[Path, Argument(help='Source file or directory with frontmatter')], output_dir: Annotated[Optional[Path], Option(--output, -o, help='Output directory')] = None, template_dirs: Annotated[Optional[List[Path]], Option(--template - dir, -t, help='Additional template directories')] = None, local_plugins: Annotated[Optional[List[str]], Option(--local - plugins, -l, help='Python modules containing local plugins')] = None, ignore: Annotated[Optional[List[str]], Option(--ignore, help='Glob patterns to ignore in source directory')] = None, verbose: Annotated[Optional[bool], Option(--verbose, -v, help='Enable verbose output')] = None) -> None

Generate documentation from source files with frontmatter.

Configuration is loaded from griffonner.yml/griffonner.yaml or pyproject.toml. CLI arguments override configuration file values.

main 

main() -> None

Main entry point for the CLI.

main_callback 

main_callback(version: Annotated[Optional[bool], Option(--version, callback=version_callback, is_eager=True, help='Show version')] = None) -> None

Main callback to handle global options.

plugins_cmd 

plugins_cmd(local_plugins: Annotated[Optional[List[str]], Option(--local - plugins, -l, help='Python modules containing local plugins')] = None, verbose: Annotated[Optional[bool], Option(--verbose, -v, help='Enable verbose output')] = None) -> None

List all available plugins (processors, filters, bundles).

Configuration is loaded from griffonner.yml/griffonner.yaml or pyproject.toml. CLI arguments override configuration file values.

setup_logging 

setup_logging(verbose: bool = False) -> None

Set up logging configuration.

Parameters:

  • verbose

    (bool, default: False ) –

    Enable verbose logging if True

templates 

templates(template_dirs: Annotated[Optional[List[Path]], Option(--template - dir, -t, help='Template directories to search')] = None, pattern: Annotated[Optional[str], Option(--pattern, -p, help='Pattern to match templates')] = None, verbose: Annotated[Optional[bool], Option(--verbose, -v, help='Enable verbose output')] = None) -> None

List available templates.

Configuration is loaded from griffonner.yml/griffonner.yaml or pyproject.toml. CLI arguments override configuration file values.

validate 

validate(template_path: Annotated[str, Argument(help='Template path to validate')], template_dirs: Annotated[Optional[List[Path]], Option(--template - dir, -t, help='Template directories to search')] = None, verbose: Annotated[Optional[bool], Option(--verbose, -v, help='Enable verbose output')] = None) -> None

Validate template syntax and structure.

Configuration is loaded from griffonner.yml/griffonner.yaml or pyproject.toml. CLI arguments override configuration file values.

version_callback 

version_callback(value: bool) -> None

Print version and exit if –version is provided.

watch 

watch(source: Annotated[Path, Argument(help='Source directory to watch')], output_dir: Annotated[Optional[Path], Option(--output, -o, help='Output directory')] = None, template_dirs: Annotated[Optional[List[Path]], Option(--template - dir, -t, help='Additional template directories')] = None, local_plugins: Annotated[Optional[List[str]], Option(--local - plugins, -l, help='Python modules containing local plugins')] = None, ignore: Annotated[Optional[List[str]], Option(--ignore, help='Glob patterns to ignore in source directory')] = None, verbose: Annotated[Optional[bool], Option(--verbose, -v, help='Enable verbose output')] = None) -> None

Watch source directory for changes and regenerate documentation.

Configuration is loaded from griffonner.yml/griffonner.yaml or pyproject.toml. CLI arguments override configuration file values.

griffonner.frontmatter

YAML frontmatter parsing and validation.

YAML frontmatter parsing for Griffonner.

Classes:

Functions:

FrontmatterConfig

Bases: BaseModel

Configuration parsed from frontmatter.

Methods:

validate_template classmethod 

validate_template(v: str) -> str

Validate template path format.

OutputItem

Bases: BaseModel

Single output configuration.

ParsedFile

Bases: BaseModel

A parsed file with frontmatter and content.

ProcessorConfig

Bases: BaseModel

Configuration for processors.

find_frontmatter_files 

find_frontmatter_files(directory: Path) -> List[Path]

Find all files with frontmatter in a directory.

Parameters:

  • directory

    (Path) –

    Directory to search

Returns:

  • List[Path] –

    List of paths to files with frontmatter

Raises:

parse_frontmatter_file 

parse_frontmatter_file(file_path: Path) -> ParsedFile

Parse a file with YAML frontmatter.

Parameters:

  • file_path

    (Path) –

    Path to the file to parse

Returns:

  • ParsedFile –

    ParsedFile with frontmatter config and content

Raises:

griffonner.griffe_wrapper

Griffe integration for Python code analysis.

Minimal Griffe integration for Griffonner.

Classes:

Functions:

GriffeError

Bases: Exception

Base exception for Griffe-related errors.

ModuleLoadError

Bases: GriffeError

Exception raised when a module cannot be loaded.

load_griffe_object 

load_griffe_object(target: str, search_paths: Optional[List[Path]] = None, griffe_config: Optional[Dict[str, Any]] = None) -> Union[Object, Alias]

Load a Griffe object using flexible configuration.

Parameters:

  • target

    (str) –

    Module name (e.g., ‘mypackage.utils’, ‘os’, ‘pathlib’)

  • search_paths

    (Optional[List[Path]], default: None ) –

    Additional paths to search for modules

  • griffe_config

    (Optional[Dict[str, Any]], default: None ) –

    Griffe configuration with loader options and method calls

Returns:

  • Union[Object, Alias] –

    Raw Griffe object

Raises:

griffonner.templates

Template discovery, loading, and validation.

Template discovery and loading for Griffonner.

Classes:

TemplateError

Bases: Exception

Base exception for template-related errors.

TemplateLoader 

TemplateLoader(template_dirs: Optional[List[Path]] = None, plugin_manager: Optional[PluginManager] = None)

Handles template discovery and loading.

Parameters:

  • template_dirs

    (Optional[List[Path]], default: None ) –

    Directories to search for templates

  • plugin_manager

    (Optional[PluginManager], default: None ) –

    Optional plugin manager for custom filters

Methods:

find_default_template 

find_default_template(object_kind: str, language: str = 'python') -> Optional[str]

Find the default template for a given object kind.

Parameters:

  • object_kind

    (str) –

    Type of object (module, class, function)

  • language

    (str, default: 'python' ) –

    Programming language (default: python)

Returns:

  • Optional[str] –

    Template path if found, None otherwise

find_templates 

find_templates(pattern: str = '**/*.jinja2') -> List[Path]

Find all templates matching a pattern.

Parameters:

  • pattern

    (str, default: '**/*.jinja2' ) –

    Glob pattern to match templates

Returns:

  • List[Path] –

    List of template paths relative to search directories

get_available_template_sets 

get_available_template_sets() -> List[str]

Get list of available template sets.

Returns:

  • List[str] –

    List of template set paths (e.g., [‘python/default’, ‘python/custom’])

load_template 

load_template(template_path: str) -> Template

Load a template by path.

Parameters:

  • template_path

    (str) –

    Relative path to template

Returns:

  • Template –

    Loaded Jinja2 template

Raises:

render_template 

render_template(template_path: str, context: Dict[str, Any]) -> str

Render a template with the given context.

Parameters:

  • template_path

    (str) –

    Relative path to template

  • context

    (Dict[str, Any]) –

    Template context variables

Returns:

  • str –

    Rendered template content

Raises:

suggest_template 

suggest_template(template_path: str) -> List[str]

Suggest alternative templates when a template is not found.

Parameters:

  • template_path

    (str) –

    The template path that was not found

Returns:

  • List[str] –

    List of suggested template paths

validate_template 

validate_template(template_path: str) -> None

Validate a template for syntax errors.

Parameters:

  • template_path

    (str) –

    Relative path to template

Raises:

TemplateNotFoundError

Bases: TemplateError

Exception raised when a template cannot be found.

TemplateValidationError

Bases: TemplateError

Exception raised when a template fails validation.

griffonner.watcher

File system watcher for development workflows.

File system watcher for Griffonner.

Classes:

DocumentationWatcher 

DocumentationWatcher(source_dir: Path, output_dir: Path, template_dirs: Optional[List[Path]] = None, plugin_manager: Optional[PluginManager] = None, ignore_patterns: Optional[List[str]] = None, default_griffe_config: Optional[Dict[str, Any]] = None)

Watches for changes in documentation source files.

Parameters:

  • source_dir

    (Path) –

    Directory to watch for changes

  • output_dir

    (Path) –

    Output directory for generated files

  • template_dirs

    (Optional[List[Path]], default: None ) –

    Additional template directories

  • plugin_manager

    (Optional[PluginManager], default: None ) –

    Optional plugin manager for processors/filters

  • ignore_patterns

    (Optional[List[str]], default: None ) –

    Glob patterns to ignore

  • default_griffe_config

    (Optional[Dict[str, Any]], default: None ) –

    Default Griffe config to merge with frontmatter

Methods:

  • start –

    Start watching for file changes.

  • stop –

    Stop watching for file changes.

  • watch –

    Start watching and block until interrupted.

start 

start() -> None

Start watching for file changes.

stop 

stop() -> None

Stop watching for file changes.

watch 

watch() -> None

Start watching and block until interrupted.

GriffonnerEventHandler 

GriffonnerEventHandler(source_dir: Path, output_dir: Path, template_dirs: Optional[List[Path]] = None, plugin_manager: Optional[PluginManager] = None, ignore_patterns: Optional[List[str]] = None, default_griffe_config: Optional[Dict[str, Any]] = None)

Bases: FileSystemEventHandler

Handles file system events for Griffonner.

Parameters:

  • source_dir

    (Path) –

    Directory to watch for changes

  • output_dir

    (Path) –

    Output directory for generated files

  • template_dirs

    (Optional[List[Path]], default: None ) –

    Additional template directories

  • plugin_manager

    (Optional[PluginManager], default: None ) –

    Optional plugin manager for processors/filters

  • ignore_patterns

    (Optional[List[str]], default: None ) –

    Glob patterns to ignore

  • default_griffe_config

    (Optional[Dict[str, Any]], default: None ) –

    Default Griffe config to merge with frontmatter

Methods:

on_created 

on_created(event: FileSystemEvent) -> None

Handle file creation events.

Parameters:

  • event

    (FileSystemEvent) –

    File system event

on_modified 

on_modified(event: FileSystemEvent) -> None

Handle file modification events.

Parameters:

  • event

    (FileSystemEvent) –

    File system event