doc: extensions: Add ability to edit doc page on GitHub

Update the vcs_link extension to also support generating "edit" URL
vcs_link_version is also now a Sphinx config making its value available
to extensions.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
This commit is contained in:
Benjamin Cabé 2023-09-25 11:26:08 +02:00 committed by Carles Cufí
commit eb1968fa10
3 changed files with 16 additions and 7 deletions

View file

@ -16,6 +16,7 @@ template to obtain VCS page URLs.
Configuration options
=====================
- ``vcs_link_version``: VCS version to use in the URL (e.g. "main")
- ``vcs_link_base_url``: Base URL used as a prefix for generated URLs.
- ``vcs_link_prefixes``: Mapping of pages (regex) <> VCS prefix.
- ``vcs_link_exclude``: List of pages (regex) that will not report a URL. Useful
@ -33,11 +34,12 @@ from sphinx.application import Sphinx
__version__ = "0.1.0"
def vcs_link_get_url(app: Sphinx, pagename: str) -> Optional[str]:
def vcs_link_get_url(app: Sphinx, pagename: str, mode: str = "blob") -> Optional[str]:
"""Obtain VCS URL for the given page.
Args:
app: Sphinx instance.
mode: Typically "edit", or "blob".
pagename: Page name (path).
Returns:
@ -60,6 +62,8 @@ def vcs_link_get_url(app: Sphinx, pagename: str) -> Optional[str]:
return "/".join(
[
app.config.vcs_link_base_url,
mode,
app.config.vcs_link_version,
found_prefix,
app.env.project.doc2path(pagename, basedir=False),
]
@ -70,12 +74,17 @@ def add_jinja_filter(app: Sphinx):
if app.builder.name != "html":
return
app.builder.templates.environment.filters["vcs_link_get_url"] = partial(
vcs_link_get_url, app
app.builder.templates.environment.filters["vcs_link_get_blob_url"] = partial(
vcs_link_get_url, app, mode="blob"
)
app.builder.templates.environment.filters["vcs_link_get_edit_url"] = partial(
vcs_link_get_url, app, mode="edit"
)
def setup(app: Sphinx):
app.add_config_value("vcs_link_version", "", "")
app.add_config_value("vcs_link_base_url", "", "")
app.add_config_value("vcs_link_prefixes", {}, "")
app.add_config_value("vcs_link_exclude", [], "")

View file

@ -19,9 +19,9 @@
</li>
<li class="wy-breadcrumbs-aside">
{%- if display_vcs_link %}
{% set vcs_url = pagename | vcs_link_get_url %}
{% if vcs_url %}
<a href="{{ vcs_url }}" class="fa fa-github"> {{ _('Open on GitHub') }}</a>
{% set vcs_blob_url = pagename | vcs_link_get_blob_url %}
{% if vcs_blob_url %}
<a href="{{ vcs_blob_url }}" class="fa fa-github"> {{ _('Open on GitHub') }}</a>
{% endif %}
{% endif %}
</li>

View file

@ -264,7 +264,7 @@ notfound_urls_prefix = f"/{version}/" if is_release else "/latest/"
# -- Options for zephyr.vcs_link ------------------------------------------
vcs_link_version = f"v{version}" if is_release else "main"
vcs_link_base_url = f"https://github.com/zephyrproject-rtos/zephyr/blob/{vcs_link_version}"
vcs_link_base_url = f"https://github.com/zephyrproject-rtos/zephyr"
vcs_link_prefixes = {
"samples/.*": "",
"boards/.*": "",