tessl/pypi-sphinx-toolbox

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

Overview

Eval results

Files

Content Creation Extensions

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

Enhanced directives and tools for creating rich documentation content including code blocks, examples, installation instructions, shields, and collapsible sections. These extensions provide modern documentation features that go beyond basic Sphinx capabilities.

Capabilities

Enhanced Code Blocks

Advanced code block directives with additional features like tab width control, execution counts, and Jupyter-style cells.

class CodeBlock(SphinxDirective):
    """Enhanced code-block directive with adjustable tab width."""
    
    option_spec = {
        'linenos': directives.flag,
        'tab-width': directives.positive_int,
        'class': directives.class_option,
        # ... other standard code-block options
    }

class CodeCell(SphinxDirective):
    """Jupyter-style code block with execution count."""
    
    option_spec = {
        'execution-count': directives.positive_int,
        'linenos': directives.flag,
        'tab-width': directives.positive_int,
    }

class OutputCell(SphinxDirective):
    """Output cell variant of CodeCell for showing results."""
    
    option_spec = {
        'execution-count': directives.positive_int,
        'class': directives.class_option,
    }

class Prompt(Element):
    """Cell prompt node for CodeCell and OutputCell."""

Usage in reStructuredText:

.. code-block:: python
   :tab-width: 4
   :linenos:
   
   def example():
       return "Hello, World!"

.. code-cell:: python
   :execution-count: 1
   
   print("Hello from Jupyter-style cell!")

.. output-cell::
   :execution-count: 1
   
   Hello from Jupyter-style cell!

Installation Instructions

Tabbed installation instructions supporting multiple package managers and installation methods.

class InstallationDirective(SphinxDirective):
    """Creates tabbed installation instructions."""
    
    option_spec = {
        'pypi': directives.flag,
        'conda': directives.flag, 
        'github': directives.unchanged,
        'extra': directives.unchanged,
    }
    
    def run(self) -> List[Node]: ...

Usage:

.. installation:: package-name
   :pypi:
   :conda:
   :github: user/repo

.. installation:: complex-package
   :pypi:
   :extra: extra-requirements

Shield and Badge Generation

Comprehensive shield/badge generation for project status, package information, and various metrics.

# PyPI shields
class PyPIShieldDirective(SphinxDirective):
    """Generate PyPI package information shields."""

def make_pypi_shield(name: str, type_: str = "version") -> str:
    """
    Create PyPI shield URL.
    
    Args:
        name: Package name
        type_: Shield type ("version", "downloads", "license", etc.)
        
    Returns:
        Shield image URL
    """

# ReadTheDocs shields  
class RTFDShieldDirective(SphinxDirective):
    """Generate ReadTheDocs build status shields."""

def make_rtfd_shield(project: str) -> str:
    """
    Create ReadTheDocs shield URL.
    
    Args:
        project: ReadTheDocs project name
        
    Returns:
        Shield image URL
    """

# GitHub shields
class GitHubShieldDirective(SphinxDirective):
    """Generate GitHub repository shields."""

def make_github_shield(username: str, repository: str, type_: str = "stars") -> str:
    """
    Create GitHub shield URL.
    
    Args:
        username: GitHub username
        repository: Repository name  
        type_: Shield type ("stars", "forks", "issues", etc.)
        
    Returns:
        Shield image URL
    """

# Maintenance status
class MaintainedShieldDirective(SphinxDirective):
    """Generate maintenance status shields."""

# License shields
class LicenseShieldDirective(SphinxDirective):
    """Generate license shields."""

# And many more shield types...

Usage:

.. shields::
   :pypi:
   :github:
   :rtfd:
   :license:

.. pypi-shield:: package-name
   :alt: PyPI version

.. github-shield:: user/repo
   :type: stars
   :alt: GitHub stars

reStructuredText Examples

Show reStructuredText source alongside its rendered output for documentation and tutorials.

class reSTExampleDirective(SphinxDirective):
    """Shows reStructuredText source and rendered output side-by-side."""
    
    option_spec = {
        'no-trim': directives.flag,
        'class': directives.class_option,
    }

def make_rest_example(
    options: Dict[str, Any], 
    env: sphinx.environment.BuildEnvironment, 
    content: List[str]
) -> List[Node]:
    """
    Create rest example content nodes.
    
    Args:
        options: Directive options
        env: Sphinx build environment
        content: reStructuredText content lines
        
    Returns:
        List of nodes for source and rendered output
    """

# Node management
rest_example_purger: Purger

Usage:

.. rest-example::
   
   This is **bold** text and this is *italic* text.
   
   .. note::
      This is a note.

Collapsible Content

Create collapsible content sections for better document organization.

class CollapseDirective(SphinxDirective):
    """Creates collapsible content sections."""
    
    option_spec = {
        'class': directives.class_option,
        'open': directives.flag,
    }
    
    def run(self) -> List[Node]: ...

Usage:

.. collapse:: Click to expand
   :open:
   
   This content can be collapsed and expanded.
   
   It supports any reStructuredText content.

Asset Links

Enhanced asset linking that opens files in browser instead of downloading.

class AssetNode(Element):
    """Node representing links to assets."""

def asset_role(
    name: str, 
    rawtext: str, 
    text: str, 
    lineno: int, 
    inliner: Inliner, 
    options: Dict[str, Any] = {}, 
    content: List[str] = []
) -> Tuple[List[Node], List[system_message]]:
    """
    Role for linking to assets that open in browser.
    
    Args:
        name: Role name
        rawtext: Raw text content
        text: Asset path or URL
        lineno: Line number in source
        inliner: Sphinx inliner object
        options: Role options
        content: Role content
        
    Returns:
        Tuple of created nodes and system messages
    """

# Node visitors
def visit_asset_node(translator: HTML5Translator, node: AssetNode) -> None: ...
def depart_asset_node(translator: HTML5Translator, node: AssetNode) -> None: ...

Usage:

:asset:`path/to/document.pdf`
:asset:`https://example.com/image.png`

CSS and Asset Management

Functions for managing CSS files and static assets in extensions.

def copy_asset_files(app: Sphinx, exception: Optional[Exception]) -> None:
    """
    Copy CSS and other asset files to build output directory.
    
    Args:
        app: Sphinx application instance
        exception: Build exception if any occurred
    """

def configure(app: Sphinx, config: Config) -> None:
    """
    Configure LaTeX elements and other build settings.
    
    Args:
        app: Sphinx application instance
        config: Sphinx configuration object
    """

Sidebar Links

Add navigation links to document sidebars.

class SidebarLinksDirective(SphinxDirective):
    """Adds navigation links to sidebar."""
    
    option_spec = {
        'caption': directives.unchanged,
        'class': directives.class_option,
    }
    
    def run(self) -> List[Node]: ...

Usage:

.. sidebar-links::
   :caption: Quick Links
   
   * `Documentation <https://docs.example.com>`_
   * `GitHub <https://github.com/user/repo>`_
   * `Issues <https://github.com/user/repo/issues>`_

Documentation Summary

Auto-generate documentation summaries and overviews.

class DocumentationSummaryDirective(SphinxDirective):
    """Generates auto-generated documentation summaries."""
    
    option_spec = {
        'depth': directives.positive_int,
        'include': directives.unchanged,
        'exclude': directives.unchanged,
    }
    
    def run(self) -> List[Node]: ...

Usage:

.. documentation-summary::
   :depth: 2
   :include: api/*
   :exclude: internal/*

Changeset Documentation

Track and document changes across versions with changeset directives.

class ChangesetDirective(SphinxDirective):
    """Documents version changesets and release notes."""
    
    option_spec = {
        'version': directives.unchanged,
        'date': directives.unchanged,
        'type': directives.unchanged,  # 'added', 'changed', 'deprecated', 'removed', 'fixed', 'security'
    }
    
    def run(self) -> List[Node]: ...

def process_changesets(app: Sphinx, doctree: Element, docname: str) -> None:
    """Process changeset nodes for version tracking."""

Usage:

.. changeset:: 2.1.0
   :date: 2023-12-01
   :type: added
   
   * New feature for enhanced documentation
   * Added support for custom themes
   
.. changeset:: 2.1.0
   :type: fixed
   
   * Fixed issue with cross-references
   * Improved error handling

Text Formatting Enhancements

Enhanced text formatting directives and roles for improved typography.

class FormattingDirective(SphinxDirective):
    """Enhanced text formatting capabilities."""
    
    option_spec = {
        'style': directives.unchanged,
        'class': directives.class_option,
    }

# Formatting roles
def kbd_role() -> Tuple[List[Node], List[system_message]]  # :kbd: role for keyboard keys
def abbr_role() -> Tuple[List[Node], List[system_message]]  # :abbr: role for abbreviations  
def menuselection_role() -> Tuple[List[Node], List[system_message]]  # Enhanced menu selection
def guilabel_role() -> Tuple[List[Node], List[system_message]]  # Enhanced GUI label formatting

Usage:

Press :kbd:`Ctrl+C` to copy.
The :abbr:`API (Application Programming Interface)` is documented here.
Go to :menuselection:`File --> Open --> Recent Files` to access recent documents.
Click the :guilabel:`Save` button.

Install with Tessl CLI