tessl/pypi-pydata-sphinx-theme

Bootstrap-based Sphinx theme from the PyData community

—

Pending

Overview

Eval results

Files

Edit Page Integration

Name: tessl/pypi-pydata-sphinx-theme
Author: tessl

Functionality for generating "edit this page" links that work with GitHub, GitLab, and Bitbucket repositories, supporting custom URL templates and multiple version control platforms.

Capabilities

Edit URL Generation

Generates edit URLs for version control platforms and injects them into template context.

def setup_edit_url(
    app: Sphinx, pagename: str, templatename: str, context, doctree
) -> None:
    """
    Add a function that jinja can access for returning the edit URL of a page.
    
    This function adds a 'get_edit_provider_and_url' function to the template
    context that generates edit URLs for GitHub, GitLab, Bitbucket, or custom
    providers based on the configuration.
    
    Parameters:
    - app (Sphinx): Sphinx application instance
    - pagename (str): Name of the current page being processed
    - templatename (str): Template being used  
    - context: Template context dictionary
    - doctree: Document tree for the current page
    
    The function also sets theme_show_toc_level as an integer in the context.
    """

Configuration

GitHub Integration

# conf.py
html_context = {
    "github_user": "username",
    "github_repo": "repository", 
    "github_version": "main",  # branch/tag name
    "doc_path": "docs/",       # path to docs in repo
}

html_theme_options = {
    "use_edit_page_button": True
}

GitLab Integration

# conf.py  
html_context = {
    "gitlab_user": "username",
    "gitlab_repo": "repository",
    "gitlab_version": "main",
    "doc_path": "docs/",
}

html_theme_options = {
    "use_edit_page_button": True
}

Bitbucket Integration

# conf.py
html_context = {
    "bitbucket_user": "username", 
    "bitbucket_repo": "repository",
    "bitbucket_version": "main",
    "doc_path": "docs/",
}

html_theme_options = {
    "use_edit_page_button": True
}

Custom URL Template

# conf.py - Custom edit URL pattern
html_context = {
    "edit_page_url_template": "https://myforge.com/{{ user }}/{{ repo }}/edit/{{ version }}/{{ file_name }}",
    "edit_page_provider_name": "MyForge",
    "user": "username",
    "repo": "repository", 
    "version": "main",
    "doc_path": "documentation/",
}

html_theme_options = {
    "use_edit_page_button": True
}

URL Templates

The edit URLs are generated using the following templates:

GitHub

{{ github_url }}/{{ github_user }}/{{ github_repo }}/edit/{{ github_version }}/{{ doc_path }}{{ file_name }}

GitLab

{{ gitlab_url }}/{{ gitlab_user }}/{{ gitlab_repo }}/-/edit/{{ gitlab_version }}/{{ doc_path }}{{ file_name }}

Bitbucket

{{ bitbucket_url }}/{{ bitbucket_user }}/{{ bitbucket_repo }}/src/{{ bitbucket_version }}/{{ doc_path }}{{ file_name }}?mode=edit

Default Provider URLs

GitHub: https://github.com
GitLab: https://gitlab.com
Bitbucket: https://bitbucket.org

These can be overridden by setting the corresponding *_url context variables.

Usage Examples

Basic GitHub Setup

# conf.py
html_context = {
    "github_user": "pydata",
    "github_repo": "pydata-sphinx-theme", 
    "github_version": "main",
    "doc_path": "docs/",
}

html_theme_options = {
    "use_edit_page_button": True,
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/pydata/pydata-sphinx-theme",
            "icon": "fa-brands fa-github"
        }
    ]
}

Enterprise GitHub

# conf.py  
html_context = {
    "github_url": "https://github.enterprise.com",
    "github_user": "orgname",
    "github_repo": "project",
    "github_version": "develop",
    "doc_path": "documentation/source/",
}

Self-hosted GitLab

# conf.py
html_context = {
    "gitlab_url": "https://gitlab.mycompany.com", 
    "gitlab_user": "team",
    "gitlab_repo": "product-docs",
    "gitlab_version": "master",
    "doc_path": "docs/",
}

Complex Custom Template

# conf.py - Advanced custom template with multiple variables
html_context = {
    "edit_page_url_template": "https://forge.example.com/{{ org }}/{{ project }}/{{ repo }}/edit/{{ branch }}/{{ doc_path }}{{ file_name }}?view=edit",
    "edit_page_provider_name": "Example Forge",
    "org": "engineering",
    "project": "documentation", 
    "repo": "user-guide",
    "branch": "latest",
    "doc_path": "source/",
}

Template Context

The edit page functionality injects a get_edit_provider_and_url function into the template context that returns:

Provider name: Human-readable name (e.g., "GitHub", "GitLab")
Edit URL: Complete URL for editing the current page

Error Handling

The function raises ExtensionError in these cases:

Required configuration values are missing
Custom URL template doesn't contain {{ file_name }}
No valid provider configuration is found

TOC Level Configuration

The function also sets theme_show_toc_level as an integer in the context, controlling the depth of the table of contents display.

Required Variables

For each provider, you must provide:

GitHub: github_user, github_repo, github_version
GitLab: gitlab_user, gitlab_repo, gitlab_version Bitbucket: bitbucket_user, bitbucket_repo, bitbucket_version Custom: edit_page_url_template (must contain {{ file_name }})

Optional variables:

doc_path: Path to documentation within repository (defaults to empty)
Provider-specific base URLs (github_url, gitlab_url, bitbucket_url)

Install with Tessl CLI

npx tessl i tessl/pypi-pydata-sphinx-theme

docs

syntax-highlighting.md

template-management.md