CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-breathe

Sphinx extension that beautifully integrates Doxygen-generated documentation into Sphinx-based documentation systems

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

cli.mddocs/

Command Line Interface

The breathe-apidoc command provides batch generation of reStructuredText files from Doxygen XML output. It processes an entire Doxygen XML tree and creates individual .rst files with breathe directives for each documented element.

Capabilities

Main Command

Generate reStructuredText files with breathe directives from Doxygen XML.

breathe-apidoc [options] <rootpath>

rootpath: Required path to directory containing Doxygen's index.xml file.

Command Options

Control output generation, file handling, and content inclusion.

# Required options
-o OUTPUT_DIR, --output-dir OUTPUT_DIR    Directory to place all output

# File handling options  
-f, --force                               Overwrite existing files
-n, --dry-run                            Run without creating files
-T, --no-toc                             Don't create table of contents
-s SUFFIX, --suffix SUFFIX               File suffix (default: rst)

# Content options
-m, --members                            Include members for applicable types
-p PROJECT, --project PROJECT            Project name for generated directives
-g TYPES, --generate TYPES               Types to generate (comma-separated)

# Output options
-q, --quiet                              Suppress informational messages
--version                                Show version information

Supported Types

Types that can be generated with the -g/--generate option:

TYPEDICT = {
    "class": "Class",
    "interface": "Interface", 
    "struct": "Struct",
    "union": "Union",
    "file": "File",
    "namespace": "Namespace",
    "group": "Group"
}

Types supporting :members: option: class, group, interface, namespace, struct

Core Functions

Functions that power the breathe-apidoc command:

def main() -> None
    """Main entry point for breathe-apidoc command."""

def recurse_tree(args) -> None
    """Process entire Doxygen XML tree and create corresponding files."""

def create_package_file(package: str, package_type: str, package_id: str, args) -> None
    """Build and write individual package documentation files."""

def create_modules_toc_file(key: str, value: str, args) -> None
    """Create table of contents files for each type."""

def write_file(name: str, text: str, args) -> None
    """Write output file with specified name and content."""

def format_directive(package_type: str, package: str, args) -> str
    """Create breathe directive with appropriate options."""

def format_heading(level: int, text: str) -> str
    """Create reStructuredText heading of specified level."""

Usage Examples

Basic API Documentation Generation

Generate documentation for all supported types:

breathe-apidoc -o docs/api -f /path/to/doxygen/xml

Generate Specific Types Only

Generate only classes and namespaces:

breathe-apidoc -o docs/api -g class,namespace /path/to/doxygen/xml

Include Members with Project Name

Generate with member documentation and project specification:

breathe-apidoc -o docs/api -m -p myproject /path/to/doxygen/xml

Dry Run to Preview Output

See what would be generated without creating files:

breathe-apidoc -o docs/api -n -m /path/to/doxygen/xml

Custom File Extension

Generate .txt files instead of .rst:

breathe-apidoc -o docs/api -s txt /path/to/doxygen/xml

Quiet Mode with No Table of Contents

Generate silently without TOC files:

breathe-apidoc -o docs/api -q -T /path/to/doxygen/xml

Output Structure

The command creates a structured directory layout:

output_dir/
├── class/
│   ├── MyClass_8cpp.rst      # Individual class files
│   └── AnotherClass_8cpp.rst
├── namespace/
│   ├── MyNamespace.rst       # Individual namespace files
│   └── AnotherNamespace.rst
├── file/
│   ├── header_8h.rst         # Individual file documentation
│   └── source_8cpp.rst
├── classlist.rst             # Table of contents for classes
├── namespacelist.rst         # Table of contents for namespaces
└── filelist.rst              # Table of contents for files

Generated File Format

Each generated file contains:

File Header

ReStructuredText heading with element type and name.

Breathe Directive

Appropriate directive (doxygenclass, doxygennamespace, etc.) with:

  • :project: option if specified
  • :members: option for applicable types if -m flag used

Example Generated Class File

Class MyClass
=============

.. doxygenclass:: MyClass
   :project: myproject
   :members:

Example Generated Table of Contents

Class list
==========

.. toctree::
   :glob:

   class/*

Integration with Sphinx

The generated files integrate seamlessly with Sphinx documentation:

  1. Include in toctree: Add generated list files to your main toctree
  2. Configure breathe: Ensure breathe_projects matches project names used
  3. Build documentation: Run sphinx-build as normal

Example Integration

.. toctree::
   :maxdepth: 2
   
   api/classlist
   api/namespacelist
   api/filelist

Error Handling

The command validates inputs and provides clear error messages:

  • Checks that rootpath is a valid directory
  • Verifies index.xml exists in rootpath
  • Creates output directory if it doesn't exist
  • Validates generate types against supported options
  • Handles file writing permissions and conflicts

Common error scenarios:

  • Missing index.xml file
  • Invalid rootpath directory
  • Permission denied for output directory
  • Invalid type specified in --generate option

Install with Tessl CLI

npx tessl i tessl/pypi-breathe

docs

cli.md

directives.md

index.md

parsers.md

project-management.md

tile.json