tessl/pypi-sphinx-toolbox

Box of handy tools for Sphinx providing comprehensive extensions and enhancements for documentation generation.

Overview

Eval results

Files

Tweaks and Enhancements

Name: tessl/pypi-sphinx-toolbox
Author: tessl

Small but important improvements to Sphinx functionality including tab size handling, parameter formatting, footnote symbols, and compatibility fixes. These tweaks address common pain points and enhance the user experience with subtle but valuable improvements to Sphinx's default behavior.

Capabilities

Tab Size Handling

Enhanced tab width processing for code blocks and documentation with configurable tab size detection and conversion.

def setup_tabsize_support(app: Sphinx) -> None:
    """
    Set up enhanced tab size handling for code blocks.
    
    Args:
        app: Sphinx application instance
    """

def get_tab_width(app: Sphinx, docname: str) -> int:
    """
    Get effective tab width for a document.
    
    Args:
        app: Sphinx application instance
        docname: Document name
        
    Returns:
        Tab width in spaces
    """

def convert_tabs_to_spaces(content: str, tab_width: int = 8) -> str:
    """
    Convert tabs to spaces in content.
    
    Args:
        content: Content with potential tabs
        tab_width: Number of spaces per tab
        
    Returns:
        Content with tabs converted to spaces
    """

class TabSizeProcessor:
    """Processor for handling tab size in documents."""
    
    def __init__(self, tab_width: int = 8) -> None:
        """
        Initialize tab size processor.
        
        Args:
            tab_width: Default tab width in spaces
        """
        
    def process_code_block(self, content: List[str]) -> List[str]:
        """Process code block content for consistent tab handling."""
        
    def detect_tab_width(self, content: str) -> int:
        """Detect likely tab width from content indentation."""

Parameter Dash Formatting

Enhanced parameter formatting in docstrings with proper dash handling and consistent formatting.

def format_param_dash(param_line: str) -> str:
    """
    Format parameter line with proper dash handling.
    
    Args:
        param_line: Raw parameter line from docstring
        
    Returns:
        Formatted parameter line with consistent dashes
    """

def normalize_param_formatting(docstring: str) -> str:
    """
    Normalize parameter formatting throughout docstring.
    
    Args:
        docstring: Raw docstring text
        
    Returns:
        Docstring with normalized parameter formatting
    """

class ParameterFormatter:
    """Formatter for docstring parameters."""
    
    def __init__(self, dash_style: str = 'single') -> None:
        """
        Initialize parameter formatter.
        
        Args:
            dash_style: Style of dashes to use ('single', 'double', 'em')
        """
        
    def format_parameter_list(self, params: List[str]) -> List[str]:
        """Format list of parameter descriptions."""
        
    def format_returns_section(self, returns_text: str) -> str:
        """Format returns section with consistent styling."""

Footnote Symbol Enhancements

Enhanced footnote handling with symbol support, custom numbering, and improved formatting.

class FootnoteSymbols:
    """Enhanced footnote symbol handling."""
    
    SYMBOLS = ['*', '†', '‡', '§', '¶', '‖', '**', '††', '‡‡']
    
    def __init__(self, style: str = 'symbols') -> None:
        """
        Initialize footnote symbols.
        
        Args:
            style: Footnote style ('symbols', 'numbers', 'roman', 'alpha')
        """
        
    def get_footnote_symbol(self, index: int) -> str:
        """Get footnote symbol for given index."""
        
    def reset_counters(self) -> None:
        """Reset footnote counters."""

def setup_footnote_symbols(app: Sphinx, symbol_style: str = 'symbols') -> None:
    """
    Set up enhanced footnote symbol handling.
    
    Args:
        app: Sphinx application instance
        symbol_style: Style of footnote symbols to use
    """

def revert_footnote_style(app: Sphinx) -> None:
    """
    Revert to default Sphinx footnote styling.
    
    Args:
        app: Sphinx application instance
    """

LaTeX Layout Improvements

Tweaks and enhancements for LaTeX output including spacing, headers, and formatting improvements.

def configure_latex_tweaks(app: Sphinx) -> None:
    """
    Apply comprehensive LaTeX layout improvements.
    
    Args:
        app: Sphinx application instance
    """

def improve_latex_spacing(config: Config) -> None:
    """
    Improve LaTeX spacing throughout the document.
    
    Args:
        config: Sphinx configuration object
    """

def enhance_latex_headers(config: Config) -> None:
    """
    Enhance LaTeX header formatting and spacing.
    
    Args:
        config: Sphinx configuration object
    """

def fix_latex_toc_formatting(config: Config) -> None:
    """
    Fix table of contents formatting issues in LaTeX.
    
    Args:
        config: Sphinx configuration object
    """

class LaTeXLayoutTweaks:
    """Collection of LaTeX layout improvements."""
    
    def __init__(self, config: Config) -> None: ...
    
    def apply_spacing_tweaks(self) -> None:
        """Apply spacing improvements."""
        
    def apply_header_tweaks(self) -> None:
        """Apply header formatting improvements."""
        
    def apply_toc_tweaks(self) -> None:
        """Apply table of contents improvements."""

Sphinx Panels Compatibility

Compatibility fixes and enhancements for sphinx-panels integration.

def setup_sphinx_panels_compat(app: Sphinx) -> None:
    """
    Set up sphinx-panels compatibility tweaks.
    
    Args:
        app: Sphinx application instance
    """

def fix_panels_tabs_conflict(app: Sphinx) -> None:
    """
    Fix conflicts between sphinx-panels and other tab implementations.
    
    Args:
        app: Sphinx application instance
    """

class PanelsCompatibilityLayer:
    """Compatibility layer for sphinx-panels integration."""
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def register_panels_nodes(self) -> None:
        """Register sphinx-panels nodes for compatibility."""
        
    def handle_panels_css(self) -> None:
        """Handle sphinx-panels CSS integration."""

Code Block Enhancements

Minor but useful enhancements to code block processing and display.

def enhance_code_blocks(app: Sphinx) -> None:
    """
    Apply code block enhancements.
    
    Args:
        app: Sphinx application instance
    """

def fix_code_block_indentation(content: str, base_indent: int = 0) -> str:
    """
    Fix code block indentation issues.
    
    Args:
        content: Code block content
        base_indent: Base indentation level
        
    Returns:
        Content with fixed indentation
    """

def normalize_line_endings(content: str) -> str:
    """
    Normalize line endings in code blocks.
    
    Args:
        content: Content with mixed line endings
        
    Returns:
        Content with normalized line endings
    """

HTML Output Tweaks

Small improvements to HTML output for better appearance and functionality.

def apply_html_tweaks(app: Sphinx) -> None:
    """
    Apply HTML output improvements.
    
    Args:
        app: Sphinx application instance
    """

def improve_html_tables(app: Sphinx) -> None:
    """
    Improve HTML table formatting and responsiveness.
    
    Args:
        app: Sphinx application instance
    """

def enhance_html_navigation(app: Sphinx) -> None:
    """
    Enhance HTML navigation elements.
    
    Args:
        app: Sphinx application instance
    """

class HTMLTweaks:
    """Collection of HTML output improvements."""
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def apply_table_tweaks(self) -> None:
        """Apply table formatting improvements."""
        
    def apply_navigation_tweaks(self) -> None:
        """Apply navigation improvements."""
        
    def apply_responsive_tweaks(self) -> None:
        """Apply responsive design improvements."""

Cross-Reference Improvements

Enhanced cross-referencing with better resolution and formatting.

def improve_cross_references(app: Sphinx) -> None:
    """
    Apply cross-reference improvements.
    
    Args:
        app: Sphinx application instance
    """

def enhance_xref_resolution(app: Sphinx) -> None:
    """
    Enhance cross-reference resolution logic.
    
    Args:
        app: Sphinx application instance
    """

def fix_xref_formatting(app: Sphinx) -> None:
    """
    Fix cross-reference formatting issues.
    
    Args:
        app: Sphinx application instance
    """

class CrossRefTweaks:
    """Cross-reference enhancement utilities."""
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def improve_resolution(self) -> None:
        """Improve cross-reference resolution."""
        
    def enhance_formatting(self) -> None:
        """Enhance cross-reference formatting."""

Search Improvements

Enhancements to Sphinx's built-in search functionality.

def enhance_search_index(app: Sphinx) -> None:
    """
    Enhance search index generation.
    
    Args:
        app: Sphinx application instance
    """

def improve_search_results(app: Sphinx) -> None:
    """
    Improve search result ranking and display.
    
    Args:
        app: Sphinx application instance
    """

class SearchTweaks:
    """Search functionality improvements."""
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def enhance_indexing(self) -> None:
        """Enhance search indexing."""
        
    def improve_ranking(self) -> None:
        """Improve search result ranking."""

Theme Compatibility

Compatibility improvements for various Sphinx themes.

def ensure_theme_compatibility(app: Sphinx, theme_name: str) -> None:
    """
    Ensure compatibility with specified theme.
    
    Args:
        app: Sphinx application instance
        theme_name: Name of the theme
    """

def fix_theme_css_conflicts(app: Sphinx) -> None:
    """
    Fix CSS conflicts with themes.
    
    Args:
        app: Sphinx application instance
    """

class ThemeCompatibility:
    """Theme compatibility utilities."""
    
    SUPPORTED_THEMES = ['alabaster', 'sphinx_rtd_theme', 'furo', 'book_theme']
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def detect_theme(self) -> str:
        """Detect current theme."""
        
    def apply_theme_fixes(self, theme_name: str) -> None:
        """Apply fixes for specific theme."""

Performance Optimizations

Small performance optimizations for faster documentation builds.

def apply_performance_tweaks(app: Sphinx) -> None:
    """
    Apply performance optimization tweaks.
    
    Args:
        app: Sphinx application instance
    """

def optimize_node_processing(app: Sphinx) -> None:
    """
    Optimize document node processing.
    
    Args:
        app: Sphinx application instance
    """

def cache_expensive_operations(app: Sphinx) -> None:
    """
    Add caching for expensive operations.
    
    Args:
        app: Sphinx application instance
    """

class PerformanceTweaks:
    """Performance optimization utilities."""
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def optimize_parsing(self) -> None:
        """Optimize document parsing."""
        
    def optimize_rendering(self) -> None:
        """Optimize output rendering."""
        
    def add_caching(self) -> None:
        """Add performance caching."""

Configuration Tweaks

Improvements to configuration handling and validation.

def enhance_config_validation(app: Sphinx) -> None:
    """
    Enhance configuration validation with better error messages.
    
    Args:
        app: Sphinx application instance
    """

def add_config_helpers(app: Sphinx) -> None:
    """
    Add configuration helper utilities.
    
    Args:
        app: Sphinx application instance
    """

class ConfigTweaks:
    """Configuration enhancement utilities."""
    
    def __init__(self, app: Sphinx) -> None: ...
    
    def improve_validation(self) -> None:
        """Improve configuration validation."""
        
    def add_shortcuts(self) -> None:
        """Add configuration shortcuts."""
        
    def enhance_error_messages(self) -> None:
        """Enhance configuration error messages."""

Extension Integration

Improvements to extension loading and integration.

def improve_extension_loading(app: Sphinx) -> None:
    """
    Improve extension loading with better error handling.
    
    Args:
        app: Sphinx application instance
    """

def enhance_extension_metadata(app: Sphinx) -> None:
    """
    Enhance extension metadata handling.
    
    Args:
        app: Sphinx application instance
    """

def fix_extension_conflicts(app: Sphinx) -> None:
    """
    Fix common extension conflicts.
    
    Args:
        app: Sphinx application instance
    """

Usage Examples

Configuration in conf.py:

# Enable all tweaks and enhancements
extensions = [
    'sphinx_toolbox.tweaks',
    # Individual tweak extensions
    'sphinx_toolbox.tweaks.tabsize',
    'sphinx_toolbox.tweaks.param_dash', 
    'sphinx_toolbox.tweaks.footnote_symbols',
    'sphinx_toolbox.tweaks.latex_layout',
    'sphinx_toolbox.tweaks.latex_toc',
]

# Configure tweak behavior
tabsize = 4
footnote_symbols = 'symbols'  # 'symbols', 'numbers', 'roman'
latex_tweaks_enable = True

Using in documents:

This text has a footnote [#footnote1]_ that will use symbols.

.. [#footnote1] Footnote text with enhanced formatting.

.. code-block:: python
   :tab-width: 4
   
   # This code block will have consistent tab handling
   def example():
       return "Enhanced formatting"

Install with Tessl CLI