scanpydoc.rtd_github_links

GitHub URLs for class and method pages.

This extension does two things:

1. It registers a Jinja filter called github_url() that you can use to convert a module path into a GitHub URL.

2. It configures sphinx.ext.linkcode for you if loaded after it in conf.py:

   extensions = [
       "scanpydoc",
       "sphinx.ext.linkcode",
   ]
   
   # no need to define `linkcode_resolve`
   

Configuration

Uses the following config values in conf.py:

rtd_links_prefix: os.PathLike | str = ...  # default: '.'

# sphinx book theme style
html_theme_options = dict(
    repository_url=...,
    repository_branch=...,
)
# or RTD theme style:
html_context = dict(
    github_user=...,
    github_repo=...,
    github_version=...,
)

The rtd_links_prefix is for figuring out the .py file path relative to the git root, that is to construct the path in the GitHub URL.

Which html configuration style you want to use depends on your theme, e.g. Sphinx Book Theme.

:github_url: usage

You can use the filter e.g. in autosummary templates. To configure the Sphinx Book Theme, override the autosummary/base.rst template like this:

:github_url: {{ fullname | github_url }}

{% extends "!autosummary/base.rst" %}

Functions

github_url(qualname)

Get the full GitHub URL for some object’s qualname.

Parameters:

qualname str

The full qualified name of a function, class, method or module

Return type:

str

Returns:

A GitHub URL derived from the html_context or the html_theme_options.

setup(app)

Register the github_url() Jinja filter.

Parameters:

app Sphinx

Sphinx app to set this extension up for

Return type:

dict[str, Any]

Returns:

Metadata for this extension.