scverse_doc.source

Links into the source repository: the repository icon, “edit this page”, and [source].

Declare the repository with source_repository. Whatever the selected theme understands is filled in: pydata-sphinx-theme’s html_context entries, furo’s and sphinx-book-theme’s theme options, and the navbar icon.

If conf.py lists sphinx.ext.linkcode, this also resolves that extension’s [source] links.

Hosts other than GitHub work as long as their URLs are laid out like GitHub’s, GitLab’s or Bitbucket’s; source_provider names the layout for a self-hosted one.

Configuration

source_repository

Type:

str

Default:

""

The repository URL, e.g. "https://gitlab.com/owner/name". Empty means no repository links at all.

source_branch

Type:

str

Default:

$READTHEDOCS_GIT_IDENTIFIER, else "main"

The ref the links point at. Read the Docs pull request builds fall back to the default, since they identify by PR number.

source_directory

Type:

str

Default:

"docs"

Where the documentation sources live in the repository.

source_code_directory

Type:

str

Default:

"src"

Where the importable code lives in the repository, for the [source] links. Set it to "" for a flat layout.

source_provider

Type:

str

Default:

inferred from the host

Which forge’s URL layout the repository follows: "github", "gitlab" or "bitbucket". Inferring it works for the hosted instances and for self-hosted ones whose host name contains the forge’s (gitlab.example.org); name it for anything else. An unknown forge still gets the navbar icon, just no per-page links.

What each theme gets

Theme	Reads
pydata-sphinx-theme, and so ours	html_context’s {provider}_user/_repo/_version/_url and doc_path, plus use_edit_page_button
sphinx_rtd_theme	the same, plus display_{provider}, {provider}_host and conf_py_path
furo, and anything else on sphinx-basic-ng	the source_repository/source_branch/source_directory theme options, plus display_{provider} for its footer icon – which it shows on Read the Docs only
sphinx-book-theme	the repository_url/repository_branch/repository_provider/path_to_docs theme options, plus use_repository_button, use_source_button and use_issues_button

Only the options a theme declares are written; a theme that declares none of them – alabaster, say – is left alone. Anything conf.py set itself wins.

[source] links

Listing sphinx.ext.linkcode is enough; the resolver is filled in:

extensions = ["scverse_doc.source", "sphinx.ext.linkcode"]

source_repository = "https://github.com/scverse/pertpy"
# no need to define `linkcode_resolve`

A linkcode_resolve of your own still wins.