tessl/pypi-sphinx-toolbox

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

Overview

Eval results

Files

GitHub Integration

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

Comprehensive GitHub integration providing custom Sphinx domain, roles for issues/PRs/users/repositories, and API-powered features. This integration enables seamless linking to GitHub resources with automatic title fetching and proper formatting.

Capabilities

GitHub Domain

Custom Sphinx domain that provides specialized roles and directives for GitHub integration.

class GitHubDomain(Domain):
    """Sphinx domain for GitHub.com integration."""
    
    name = 'github'
    label = 'GitHub'
    
    roles = {
        'issue': IssueRole(),
        'pull': PullRole(), 
        'user': UserRole(),
        'org': UserRole(),
        'repo': RepoRole(),
    }
    
    def clear_doc(self, docname: str) -> None: ...
    def merge_info(self, docnames: List[str], other: Domain) -> None: ...

def validate_config(app: Sphinx, config: ToolboxConfig) -> None:
    """
    Validate GitHub configuration values.
    
    Args:
        app: Sphinx application instance
        config: Configuration object to validate
        
    Raises:
        MissingOptionError: When github_username or github_repository missing
    """

Issue and Pull Request Integration

Link to GitHub issues and pull requests with automatic title fetching from the GitHub API.

class IssueNode(Element):
    """Node for GitHub issue/PR links."""

class IssueNodeWithName(Element):  
    """Issue node that includes repository name."""

def issue_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 GitHub issues.
    
    Args:
        name: Role name ('issue')
        rawtext: Raw role text
        text: Issue number or 'user/repo#number'
        lineno: Line number in document
        inliner: Sphinx inliner
        options: Role options
        content: Role content
        
    Returns:
        Tuple of issue nodes and any error messages
    """

def pull_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 GitHub pull requests.
    
    Similar signature to issue_role but for pull requests.
    """

def get_issue_title(username: str, repository: str, issue_number: int) -> str:
    """
    Fetch issue/PR title from GitHub API.
    
    Args:
        username: GitHub username or organization
        repository: Repository name
        issue_number: Issue or pull request number
        
    Returns:
        Issue/PR title from GitHub API
        
    Raises:
        requests.RequestException: If API request fails
    """

Usage:

:github:issue:`123` 
:github:issue:`user/repo#456`
:github:pull:`789`
:issue:`123`  (when github_username/github_repository configured)
:pull:`456`   (when github_username/github_repository configured)

Repository and User Links

Create links to GitHub repositories, users, and organizations.

class GitHubObjectLinkNode(Element):
    """Node for GitHub repository/user links."""

def repository_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 GitHub repositories.
    
    Args:
        name: Role name ('repo')
        rawtext: Raw role text
        text: Repository in format 'user/repo'
        lineno: Line number in document
        inliner: Sphinx inliner
        options: Role options
        content: Role content
        
    Returns:
        Tuple of repository link nodes and any error messages
    """

def user_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 GitHub users/organizations.
    
    Args:
        name: Role name ('user' or 'org')
        rawtext: Raw role text
        text: Username or organization name
        lineno: Line number in document
        inliner: Sphinx inliner
        options: Role options
        content: Role content
        
    Returns:
        Tuple of user link nodes and any error messages
    """

Usage:

:github:repo:`user/repository`
:github:user:`username`
:github:org:`organization`

Node Visitors

HTML and LaTeX visitors for rendering GitHub nodes in different output formats.

def visit_issue_node(translator: HTML5Translator, node: IssueNode) -> None:
    """
    Visit issue node during HTML translation.
    
    Args:
        translator: Sphinx HTML translator
        node: Issue node to process
    """

def depart_issue_node(translator: HTML5Translator, node: IssueNode) -> None:
    """
    Depart issue node during HTML translation.
    
    Args:
        translator: Sphinx HTML translator  
        node: Issue node being processed
    """

def visit_issue_node_latex(translator: LaTeXTranslator, node: IssueNode) -> None:
    """Visit issue node during LaTeX translation."""

def depart_issue_node_latex(translator: LaTeXTranslator, node: IssueNode) -> None:
    """Depart issue node during LaTeX translation."""

# Similar visitors for GitHubObjectLinkNode
def visit_github_object_link_node(translator: HTML5Translator, node: GitHubObjectLinkNode) -> None: ...
def depart_github_object_link_node(translator: HTML5Translator, node: GitHubObjectLinkNode) -> None: ...

Source File Links

Enhanced source file linking with GitHub integration.

def source_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 source files on GitHub or in documentation.
    
    Args:
        name: Role name ('source')
        rawtext: Raw role text
        text: File path
        lineno: Line number in document
        inliner: Sphinx inliner
        options: Role options
        content: Role content
        
    Returns:
        Tuple of source link nodes and any error messages
    """

Usage:

:source:`path/to/file.py`
:source:`module/__init__.py`

Configuration

GitHub integration requires configuration in your Sphinx conf.py:

# Required for issue/pull roles without repository specification
github_username = "your-username"
github_repository = "your-repository"

# Optional settings
source_link_target = "github"  # or "docs" 
github_url = "https://github.com"  # Custom GitHub instance

Error Handling

The GitHub integration includes proper error handling for API failures and configuration issues:

class GitHubAPIError(Exception):
    """Raised when GitHub API requests fail."""

class MissingGitHubConfigError(MissingOptionError):
    """Raised when required GitHub configuration is missing."""

API Rate Limiting

The integration includes built-in rate limiting and caching to avoid hitting GitHub API limits:

Automatic caching of API responses for 4 hours
Rate limit handling with exponential backoff
Graceful degradation when API is unavailable

Advanced Usage

For more advanced usage scenarios:

.. note::
   
   Related to :github:issue:`123` and :github:pull:`456`.
   
   See :github:repo:`related-org/related-project` for similar functionality.
   
   Thanks to :github:user:`contributor` for the implementation.

Cross-repository references:
:github:issue:`other-user/other-repo#789`
:github:pull:`other-user/other-repo#101`

Install with Tessl CLI