Main Module

Core Introligo functionality

API Documentation

Introligo - YAML to reStructuredText documentation generator for Sphinx.

Copyright (c) 2025 WT Tech Jakub Brzezowski

This is an open-source component of the Celin Project, freely available for use in any project without restrictions.

Introligo streamlines the documentation process by converting structured YAML configurations into properly formatted reStructuredText files for Sphinx.

class introligo.IncludeLoader(stream)[source]

Bases: SafeLoader

YAML loader with support for !include directive.

Allows splitting configuration across multiple files using:

!include path/to/file.yaml

Paths are resolved relative to the file containing the !include directive.

__init__(stream)[source]

Initialize the loader with file path tracking.

Parameters:

stream – YAML input stream, typically a file object.

yaml_constructors = {'!include': <function include_constructor>, 'tag:yaml.org,2002:binary': <function SafeConstructor.construct_yaml_binary>, 'tag:yaml.org,2002:bool': <function SafeConstructor.construct_yaml_bool>, 'tag:yaml.org,2002:float': <function SafeConstructor.construct_yaml_float>, 'tag:yaml.org,2002:int': <function SafeConstructor.construct_yaml_int>, 'tag:yaml.org,2002:map': <function SafeConstructor.construct_yaml_map>, 'tag:yaml.org,2002:null': <function SafeConstructor.construct_yaml_null>, 'tag:yaml.org,2002:omap': <function SafeConstructor.construct_yaml_omap>, 'tag:yaml.org,2002:pairs': <function SafeConstructor.construct_yaml_pairs>, 'tag:yaml.org,2002:seq': <function SafeConstructor.construct_yaml_seq>, 'tag:yaml.org,2002:set': <function SafeConstructor.construct_yaml_set>, 'tag:yaml.org,2002:str': <function SafeConstructor.construct_yaml_str>, 'tag:yaml.org,2002:timestamp': <function SafeConstructor.construct_yaml_timestamp>, None: <function SafeConstructor.construct_undefined>}
exception introligo.IntroligoError(message: str, context: str | None = None)[source]

Bases: Exception

Custom exception for Introligo errors.

Parameters:

  • message – The error message.

  • context – Optional additional context about the error.

message

The error message.

context

Additional context information.

__init__(message: str, context: str | None = None)[source]

Initialize the IntroligoError.

Parameters:

  • message – The error message.

  • context – Optional additional context about the error.

class introligo.IntroligoGenerator(config_file: Path, output_dir: Path, template_file: Path | None = None, dry_run: bool = False, strict: bool = False)[source]

Bases: object

Main generator class for processing YAML and creating RST files.

__init__(config_file: Path, output_dir: Path, template_file: Path | None = None, dry_run: bool = False, strict: bool = False)[source]

Initialize the Introligo generator.

Parameters:

  • config_file – Path to the YAML configuration file.

  • output_dir – Output directory for generated documentation.

  • template_file – Optional custom Jinja2 template file.

  • dry_run – If True, only show what would be generated.

  • strict – If True, fail on any generation error.

_convert_latex_to_rst(latex: str) → str[source]

Convert LaTeX content to reStructuredText math directive.

Parameters:

latex – LaTeX content to convert.

Returns:

RST-formatted math content.

auto_configure_extensions() → None[source]

Automatically configure Sphinx extensions based on detected project types.

build_page_tree() → None[source]

Build hierarchical page tree from loaded configuration.

Creates PageNode objects and establishes parent-child relationships based on the ‘parent’ field in each page’s configuration.

detect_project_languages() → set[source]

Detect programming languages used in the project.

Returns:

Set of language strings found in module configurations.

flatten_palette_colors(palette_colors: Dict[str, Any]) → Dict[str, str][source]

Flatten nested color palette into CSS variable format.

Parameters:

palette_colors – Nested color definitions from palette.

Returns:

Flattened dictionary with CSS variable names.

generate_all() → Dict[str, Tuple[str, Path]][source]

Main generation method.

Loads configuration, builds page tree, and generates all RST files.

Returns:

Dictionary mapping file paths to tuples of (content, Path).

generate_all_nodes(nodes: List[PageNode], template: Template, strict: bool = False) → Dict[str, Tuple[str, Path]][source]

Generate all RST files for the page tree.

Parameters:

  • nodes – List of PageNode objects to generate.

  • template – Jinja2 template for rendering.

  • strict – If True, raise exception on generation errors.

Returns:

Dictionary mapping file paths to tuples of (content, Path).

Raises:

IntroligoError – If strict mode is enabled and generation fails.

generate_breathe_config() → str | None[source]

Generate Breathe configuration snippet for Sphinx conf.py.

Returns:

Breathe configuration snippet as a string, or None if no Doxygen config.

generate_conf_py() → str | None[source]

Generate conf.py content from Sphinx configuration.

Returns:

Generated conf.py content as a string, or None if no Sphinx config.

generate_index(root_nodes: List[PageNode]) → str[source]

Generate the main index.rst file.

Parameters:

root_nodes – List of root PageNode objects to include in index.

Returns:

Generated index.rst content as a string.

generate_rst_content(node: PageNode, template: Template) → str[source]

Generate RST content with enhanced features support.

Parameters:

  • node – PageNode containing page configuration.

  • template – Jinja2 template for rendering.

Returns:

Generated RST content as a string.

get_default_template() → str[source]

Get the default Jinja2 template for RST generation.

Returns:

Default template string with support for rich content sections.

include_file(file_path: str) → str[source]

Include a file with auto-detection based on file extension.

Supports: - .rst: included as-is - .md: converted to RST - .tex: wrapped in math directive - .txt: wrapped in literal block

Parameters:

file_path – Path to the file (relative to config file).

Returns:

The processed content of the file.

Raises:

IntroligoError – If the file cannot be read or type is unsupported.

include_latex_file(latex_path: str) → str[source]

Include a LaTeX file as a math directive in reStructuredText.

Parameters:

latex_path – Path to the LaTeX file (relative to config file).

Returns:

The content of the LaTeX file wrapped in RST math directive.

Raises:

IntroligoError – If the LaTeX file cannot be read.

include_markdown_file(markdown_path: str) → str[source]

Include a markdown file and convert it to reStructuredText-compatible format.

Parameters:

markdown_path – Path to the markdown file (relative to config file).

Returns:

The content of the markdown file converted to RST-compatible format.

Raises:

IntroligoError – If the markdown file cannot be read.

include_rst_file(rst_path: str) → str[source]

Include a reStructuredText file as-is.

Parameters:

rst_path – Path to the RST file (relative to config file).

Returns:

The content of the RST file.

Raises:

IntroligoError – If the RST file cannot be read.

include_txt_file(txt_path: str) → str[source]

Include a text file as a literal block in reStructuredText.

Parameters:

txt_path – Path to the text file (relative to config file).

Returns:

The content of the text file wrapped in literal block.

Raises:

IntroligoError – If the text file cannot be read.

load_config() → None[source]

Load configuration with support for !include directives.

Raises:

IntroligoError – If the config file is not found, has invalid YAML, or doesn’t contain required ‘modules’ dictionary.

load_palette(palette_name: str) → Dict[str, Any][source]

Load a color palette from the palettes directory.

Parameters:

palette_name – Name of the palette (without .yaml extension) or path to palette file.

Returns:

Dictionary containing palette data.

Raises:

IntroligoError – If the palette file cannot be loaded.

load_sphinx_config() → None[source]

Load Sphinx configuration from the config file.

load_template() → Template[source]

Load template and add custom filters.

Returns:

Configured Jinja2 Template object with custom filters.

process_usage_examples(examples: Any) → List[Dict[str, Any]][source]

Process usage examples to ensure they’re in the right format.

Parameters:

examples – Usage examples in various formats (dict, list, or string).

Returns:

List of normalized example dictionaries with title, description, language, and code fields.

resolve_color_references(palette_colors: Dict[str, Any], theme_mapping: Dict[str, str]) → Dict[str, str][source]

Resolve color references in theme mapping.

Color references are in the format {color_group.shade}, e.g., {cosmic_dawn.3}.

Parameters:

  • palette_colors – Dictionary of color definitions from palette.

  • theme_mapping – Dictionary of theme variables with potential color references.

Returns:

Dictionary with all color references resolved to actual hex values. Note: Variable names starting with ‘–’ will have the prefix removed since Furo adds it automatically when generating CSS.

write_files(generated_files: Dict[str, Tuple[str, Path]]) → None[source]

Write all generated files to disk.

Parameters:

generated_files – Dictionary mapping file paths to (content, Path) tuples.

class introligo.PageNode(page_id: str, config: Dict[str, Any], parent: PageNode | None = None)[source]

Bases: object

Represents a documentation page in the hierarchy.

__init__(page_id: str, config: Dict[str, Any], parent: PageNode | None = None)[source]

Initialize a page node in the documentation tree.

Parameters:

  • page_id – Unique identifier for the page.

  • config – Configuration dictionary for the page.

  • parent – Parent PageNode, if this is a subpage.

get_output_dir(base_generated_dir: Path) → Path[source]

Get the full output directory path for this page (with full lineage).

Parameters:

base_generated_dir – Base directory for generated files.

Returns:

Full path to the output directory for this page.

get_output_file(base_generated_dir: Path) → Path[source]

Get the full output file path for this page.

Parameters:

base_generated_dir – Base directory for generated files.

Returns:

Full path to the output RST file.

get_relative_path_from(other_dir: Path, base_generated_dir: Path) → str[source]

Get relative path for toctree entries.

Parameters:

  • other_dir – Reference directory to calculate path from (parent’s directory).

  • base_generated_dir – Base directory for generated files.

Returns:

Relative path string for use in Sphinx toctree.

get_rst_filename() → str[source]

Get the RST filename for this page.

Returns:

The filename with .rst extension.

has_module() → bool[source]

Check if this node has an associated Python module.

Returns:

True if the config specifies a module, False otherwise.

is_leaf() → bool[source]

Check if this node is a leaf (has no children).

Returns:

True if the node has no children, False otherwise.

Convert markdown links to RST format.

Handles: - External links: [text](http://url) -> text - External links with anchors: [text](http://url#anchor) -> text - Internal docs with anchors: [text](./file.md#anchor) -> text (see section) - Internal docs: [text](./file.md) -> file - Anchor links: [text](#anchor) -> anchor - Images: ![alt](path) -> .. image:: path

Parameters:

text – Line of text potentially containing markdown links.

Returns:

Text with links converted to RST format.

introligo.convert_markdown_table_to_rst(lines: list, start_index: int) → tuple[source]

Convert markdown table to RST list-table directive.

Parameters:

  • lines – List of all lines in the document

  • start_index – Index where the table starts

Returns:

Tuple of (rst_lines, end_index) where rst_lines is the converted table and end_index is the index after the table ends

introligo.convert_markdown_to_rst(markdown: str, doc_type: str | None = None, demote_headers: bool = True) → str[source]

Convert basic markdown syntax to reStructuredText.

Parameters:

  • markdown – Markdown content to convert.

  • doc_type – Type of document (readme, changelog, license) for special handling.

  • demote_headers – If True, demote all headers by one level (# -> ##, ## -> ###, etc.) to avoid duplicate H1 headers when including files. Default is True.

Returns:

RST-compatible content.

introligo.count_display_width(text: str) → int[source]

Calculate display width for RST underlines, accounting for emojis.

Emojis and other wide characters need extra underline characters. This function estimates the visual width by counting emoji characters and adding extra characters to the base length.

Parameters:

text – The text to measure

Returns:

Estimated character width for RST underlines

introligo.include_constructor(loader: IncludeLoader, node: Node) → Any[source]

Construct included YAML content.

Parameters:

  • loader – The YAML loader instance

  • node – The YAML node containing the include path

Returns:

The loaded content from the included file

Raises:

IntroligoError – If the included file cannot be loaded

introligo.main() → None[source]

Main entry point for the Introligo command-line tool.

Parses command-line arguments and executes the documentation generation.

introligo.slugify(text: str) → str[source]

Convert text to ASCII-safe filesystem-compatible slug.

Parameters:

text – The text to convert to a slug.

Returns:

ASCII-safe slug suitable for filenames and URLs.