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>

doc/_extensions/zephyr/vcs_link.py

@@ -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", [], "")

doc/_templates/breadcrumbs.html

@@ -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>

doc/conf.py

@@ -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/.*": "",