stouputils.applications.automatic_docs.sphinx.forges module#

Code forge URL conventions, used to link a documented object back to its source.

Every forge agrees that a URL needs a repository, a branch and a path, and no two of them agree on the order. This module holds that knowledge in one table so the rest of the generator never has to care.

class ForgeUrls(edit: str, blob: str)[source]#

Bases: object

URL patterns of a code forge, built from a repository URL.

edit: str[source]#

Pattern for editing a file, with {repo}, {branch} and {path} placeholders.

blob: str[source]#

Pattern for viewing a file, with the same placeholders.

FORGES: dict[str, ForgeUrls] = {'bitbucket': ForgeUrls(edit='{repo}/src/{branch}/{path}?mode=edit', blob='{repo}/src/{branch}/{path}'), 'codeberg': ForgeUrls(edit='{repo}/_edit/{branch}/{path}', blob='{repo}/src/branch/{branch}/{path}'), 'github': ForgeUrls(edit='{repo}/edit/{branch}/{path}', blob='{repo}/blob/{branch}/{path}'), 'gitlab': ForgeUrls(edit='{repo}/-/edit/{branch}/{path}', blob='{repo}/-/blob/{branch}/{path}')}[source]#

Path conventions of each supported forge, since no two of them agree on where to put the branch.

get_source_url(
repo_url: str,
repo_provider: str,
repo_branch: str,
) → str[source]#

Build the linkcode template pointing at a module’s source file.

Parameters:
Returns:

URL with a remaining {filename} placeholder, empty when no repository is known

Return type:

str

Examples

>>> get_source_url("https://github.com/Stoupy51/stouputils", "github", "main")
'https://github.com/Stoupy51/stouputils/blob/main/{filename}.py'
>>> get_source_url("", "github", "main")
''
get_edit_url(
repo_url: str,
repo_provider: str,
repo_branch: str,
edit_link_path: str,
) → str[source]#

Build the “edit this page” template the theme fills with the page path.

Parameters:

  • repo_url (str) – Repository URL, ex: “https://github.com/Stoupy51/stouputils”

  • repo_provider (str) – Which key of FORGES describes the repository URL

  • repo_branch (str) – Branch the edit links point at

  • edit_link_path (str) – Where the Sphinx sources are tracked, ex: “docs/source”

Returns:

URL ending in the theme’s %s placeholder, empty when either argument is missing

Return type:

str

Examples

>>> get_edit_url("https://gitlab.com/g/p", "gitlab", "main", "docs/source")
'https://gitlab.com/g/p/-/edit/main/docs/source/%s'
>>> get_edit_url("https://gitlab.com/g/p", "gitlab", "main", "")
''