doc: extensions: add vcs_link

Add vcs_link extension. The extension can be used to obtain VCS (Git)
URLs for given Sphinx documents.

Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>

doc/_extensions/zephyr/vcs_link.py

@@ -0,0 +1,86 @@
+"""
+VCS Link
+########
+
+Copyright (c) 2021 Nordic Semiconductor ASA
+SPDX-License-Identifier: Apache-2.0
+
+Introduction
+============
+
+This Sphinx extension can be used to obtain the VCS URL for a given Sphinx page.
+This is useful, for example, when adding features like "Open on GitHub" on top
+of pages. The extension installs a Jinja filter which can be used on the
+template to obtain VCS page URLs.
+
+Configuration options
+=====================
+
+- ``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
+  for, e.g., auto-generated pages not in VCS.
+"""
+
+from functools import partial
+import os
+import re
+from typing import Optional
+
+from sphinx.application import Sphinx
+
+
+__version__ = "0.1.0"
+
+
+def vcs_link_get_url(app: Sphinx, pagename: str) -> Optional[str]:
+    """Obtain VCS URL for the given page.
+
+    Args:
+        app: Sphinx instance.
+        pagename: Page name (path).
+
+    Returns:
+        VCS URL if applicable, None otherwise.
+    """
+
+    if not os.path.isfile(app.env.project.doc2path(pagename)):
+        return None
+
+    for exclude in app.config.vcs_link_exclude:
+        if re.match(exclude, pagename):
+            return None
+
+    found_prefix = ""
+    for pattern, prefix in app.config.vcs_link_prefixes.items():
+        if re.match(pattern, pagename):
+            found_prefix = prefix
+            break
+
+    return "/".join(
+        [
+            app.config.vcs_link_base_url,
+            found_prefix,
+            app.env.project.doc2path(pagename, basedir=False),
+        ]
+    )
+
+
+def add_jinja_filter(app: Sphinx):
+    app.builder.templates.environment.filters["vcs_link_get_url"] = partial(
+        vcs_link_get_url, app
+    )
+
+
+def setup(app: Sphinx):
+    app.add_config_value("vcs_link_base_url", "", "")
+    app.add_config_value("vcs_link_prefixes", {}, "")
+    app.add_config_value("vcs_link_exclude", [], "")
+
+    app.connect("builder-inited", add_jinja_filter)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }