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

Project Management

Name: tessl/pypi-breathe
Author: tessl

Breathe's project management system handles multiple Doxygen projects, XML paths, source paths, and automatic XML generation. It provides a clean abstraction for working with Doxygen output while supporting both manual and automatic workflows.

Capabilities

ProjectInfo Class

Represents a configured Doxygen project with XML output location and metadata.

class ProjectInfo:
    def __init__(self, app: Sphinx, name: str, path: str, source_path: str, reference: str):
        """
        Initialize project information.
        
        Args:
            app: Sphinx application instance
            name: Project name identifier
            path: Path to Doxygen XML output directory  
            source_path: Path to source files for auto-generation
            reference: Reference identifier for the project
        """
    
    def name(self) -> str:
        """Get the project name identifier."""
    
    def project_path(self) -> str:
        """Get the path to Doxygen XML output directory."""
    
    def source_path(self) -> str:
        """Get the path to source files."""
    
    def relative_path_to_xml_file(self, file_: str) -> str:
        """
        Get relative path from Sphinx source directory to XML file.
        
        Args:
            file_: XML filename relative to project XML directory
            
        Returns:
            Relative path from Sphinx srcdir to the specified XML file
        """
    
    def sphinx_abs_path_to_file(self, file_: str) -> str:
        """
        Get Sphinx absolute path to XML file.
        
        Prepends os.path.sep to create Sphinx's concept of absolute path
        which starts from the top-level source directory.
        
        Args:
            file_: XML filename relative to project XML directory
            
        Returns:
            Sphinx absolute path starting with os.path.sep
        """
    
    def reference(self) -> str:
        """Get the project reference identifier."""
    
    def source_path(self) -> str:
        """Get the path to source files."""
    
    def domain_for_file(self, file_: str) -> str:
        """
        Determine Sphinx domain for a given file.
        
        Uses breathe_domain_by_extension and breathe_domain_by_file_pattern
        configuration to map files to appropriate Sphinx domains.
        
        Args:
            file_: Filename to check
            
        Returns:
            Domain name (e.g., 'py', 'cs') or empty string if no match
        """

AutoProjectInfo Class

Handles projects with automatic Doxygen XML generation from source files.

class AutoProjectInfo:
    def __init__(self, app: Sphinx, name: str, source_path: str, build_dir: str, reference: str):
        """
        Initialize auto-generation project information.
        
        Args:
            app: Sphinx application instance
            name: Project name identifier
            source_path: Path to source files for XML generation
            build_dir: Directory for generated XML output
            reference: Reference identifier for the project
        """
    
    def name(self) -> str:
        """Get the project name identifier."""
    
    def build_dir(self) -> str:
        """Get the build directory for XML generation."""
    
    def abs_path_to_source_file(self, file_: str) -> str:
        """
        Get absolute path to source file.
        
        Returns full path assuming the provided path is relative to the
        project's source directory as specified in breathe_projects_source.
        
        Args:
            file_: Filename relative to project source directory
            
        Returns:
            Absolute path to the source file
        """
    
    def create_project_info(self, project_path: str) -> ProjectInfo:
        """
        Create a standard ProjectInfo from this AutoProjectInfo.
        
        Args:
            project_path: Path where XML was generated
            
        Returns:
            ProjectInfo instance for the generated XML
        """

ProjectInfoFactory Class

Factory for creating and managing ProjectInfo instances with caching and configuration resolution.

class ProjectInfoFactory:
    def __init__(self, app: Sphinx):
        """
        Initialize the factory with Sphinx application.
        
        Args:
            app: Sphinx application instance
        """
    
    @property
    def build_dir(self) -> str:
        """
        Get build directory for auto-generation.
        
        Uses breathe_build_directory config if set, otherwise uses
        parent directory of Sphinx doctreedir.
        """
    
    def default_path(self) -> str:
        """
        Get default XML path from configuration.
        
        Returns:
            Path from breathe_projects[breathe_default_project]
            
        Raises:
            NoDefaultProjectError: If no default project configured
            ProjectError: If default project not found in breathe_projects
        """
    
    def create_project_info(self, options: dict) -> ProjectInfo:
        """
        Create ProjectInfo from directive options.
        
        Resolves project from options['project'], options['path'], or default.
        Caches created instances for reuse.
        
        Args:
            options: Directive options dictionary
            
        Returns:
            ProjectInfo instance
            
        Raises:
            ProjectError: If specified project not found in configuration
        """
    
    def store_project_info_for_auto(self, name: str, project_info: AutoProjectInfo) -> None:
        """
        Store AutoProjectInfo for auto-generation directives.
        
        Args:
            name: Project name for storage key
            project_info: AutoProjectInfo instance to store
        """
    
    def retrieve_project_info_for_auto(self, options: dict) -> AutoProjectInfo:
        """
        Retrieve stored AutoProjectInfo for auto-generation.
        
        Args:
            options: Directive options dictionary
            
        Returns:
            AutoProjectInfo instance
            
        Raises:
            NoDefaultProjectError: If no project specified and no default
        """
    
    def create_auto_project_info(self, name: str, source_path: str) -> AutoProjectInfo:
        """
        Create AutoProjectInfo for auto-generation.
        
        Caches created instances for reuse.
        
        Args:
            name: Project name identifier
            source_path: Path to source files
            
        Returns:
            AutoProjectInfo instance
        """

Configuration Integration

The project management system integrates with several Sphinx configuration values:

Required Configuration

# Project mapping - required for basic functionality
breathe_projects = {
    "project1": "/path/to/project1/xml",
    "project2": "/path/to/project2/xml"
}

# Default project when none specified in directives
breathe_default_project = "project1"

Auto-generation Configuration

# Source paths for automatic XML generation
breathe_projects_source = {
    "project1": "/path/to/project1/source",
    "project2": "/path/to/project2/source"  
}

# Build directory for generated XML (optional)
breathe_build_directory = "/custom/build/path"

Domain Configuration

# Map file extensions to Sphinx domains
breathe_domain_by_extension = {
    "py": "py",
    "cs": "cs",
    "java": "java"
}

# Map file patterns to Sphinx domains  
breathe_domain_by_file_pattern = {
    "*/python/*": "py",
    "*/csharp/*": "cs"
}

Usage Examples

Basic Project Setup

# In conf.py
breathe_projects = {
    "mylib": "doxygen/xml"
}
breathe_default_project = "mylib"

# In directive
.. doxygenclass:: MyClass
   :project: mylib

Multiple Projects

# In conf.py
breathe_projects = {
    "core": "build/core/xml",
    "plugins": "build/plugins/xml",
    "examples": "build/examples/xml"
}
breathe_default_project = "core"

# In directives
.. doxygenclass:: CoreClass
   :project: core

.. doxygenclass:: PluginClass  
   :project: plugins

Auto-generation Setup

# In conf.py
breathe_projects_source = {
    "mylib": "src/"
}
breathe_doxygen_config_options = {
    "EXTRACT_ALL": "YES",
    "EXTRACT_PRIVATE": "YES"
}

# Auto directives generate XML automatically
.. autodoxygenfile:: myheader.h
   :project: mylib

Custom Build Directory

# In conf.py  
breathe_build_directory = "/tmp/breathe_build"
breathe_projects_source = {
    "mylib": "src/"
}

# XML will be generated in /tmp/breathe_build/mylib/

Domain-specific Configuration

# In conf.py
breathe_domain_by_extension = {
    "py": "py",
    "cs": "cs"  
}
breathe_domain_by_file_pattern = {
    "*/bindings/*.py": "py",
    "*/managed/*.cs": "cs"
}

# Files will be processed with appropriate domain settings

Programmatic Access

from breathe.project import ProjectInfoFactory

# In Sphinx extension
def setup(app):
    factory = ProjectInfoFactory(app)
    
    # Create project info from options
    options = {"project": "mylib"}
    project_info = factory.create_project_info(options)
    
    # Use project info
    xml_path = project_info.project_path()
    domain = project_info.domain_for_file("example.py")

Exception Classes

class ProjectError(BreatheError):
    """Raised when project configuration or resolution fails."""

class NoDefaultProjectError(ProjectError):
    """Raised when no default project is configured but required."""

Common scenarios:

ProjectError: Invalid project name in directive options
NoDefaultProjectError: No :project: option and no breathe_default_project set
ProjectError: Default project name not found in breathe_projects dictionary