doc: Make it easier to report issues in the documentation

- Add extension to get git metadata (date, SHA-1, ...) regarding the
  latest update made to a page
- Add date of last "actual" update to each manually authored doc page
- Add admonition inviting to report issues
- Add button in breadcrumb to report issue

Fixes #60622.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>

doc/_extensions/zephyr/git_info.py

@@ -0,0 +1,103 @@
+"""
+Git Info Extension
+##################
+
+Copyright (c) 2023 The Linux Foundation
+SPDX-License-Identifier: Apache-2.0
+
+Introduction
+============
+
+This extension adds a new Jinja filter, ``git_info``, that returns the date and SHA1 of the last
+commit made to a page if this page is managed by Git.
+"""
+
+import os
+import re
+import subprocess
+from datetime import datetime
+from functools import partial
+from pathlib import Path
+from typing import Optional
+from typing import Tuple
+
+from sphinx.application import Sphinx
+from sphinx.util.i18n import format_date
+
+__version__ = "0.1.0"
+
+
+def git_info_filter(app: Sphinx, pagename) -> Optional[Tuple[str, str]]:
+    """Return a tuple with the date and SHA1 of the last commit made to a page.
+
+    Arguments:
+        app {Sphinx} -- Sphinx application object
+        pagename {str} -- Page name
+
+    Returns:
+        Optional[Tuple[str, str]] -- Tuple with the date and SHA1 of the last commit made to the
+        page, or None if the page is not in the repo.
+    """
+
+    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
+
+    orig_path = os.path.join(
+        app.config.ZEPHYR_BASE,
+        found_prefix,
+        app.env.project.doc2path(pagename, basedir=False),
+    )
+
+    try:
+        date_and_sha1 = (
+            subprocess.check_output(
+                [
+                    "git",
+                    "log",
+                    "-1",
+                    "--format=%ad %H",
+                    "--date=unix",
+                    orig_path,
+                ],
+                stderr=subprocess.STDOUT,
+            )
+            .decode("utf-8")
+            .strip()
+        )
+        date, sha1 = date_and_sha1.split(" ", 1)
+        date_object = datetime.fromtimestamp(int(date))
+        last_update_fmt = app.config.html_last_updated_fmt
+        if last_update_fmt is not None:
+            date = format_date(last_update_fmt, date=date_object, language=app.config.language)
+
+        return (date, sha1)
+    except subprocess.CalledProcessError:
+        return None
+
+
+def add_jinja_filter(app: Sphinx):
+    if app.builder.name != "html":
+        return
+
+    app.builder.templates.environment.filters["git_info"] = partial(git_info_filter, app)
+
+
+def setup(app: Sphinx):
+    app.add_config_value("ZEPHYR_BASE", Path(__file__).resolve().parents[3], "html")
+    app.connect("builder-inited", add_jinja_filter)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

doc/_extensions/zephyr/vcs_link.py

@@ -91,12 +91,15 @@ def vcs_link_get_open_issue_url(app: Sphinx, pagename: str, sha1: str) -> Option
     if not os.path.isfile(app.env.project.doc2path(pagename)):
         return None
 
-    title = quote(f"[doc] Issue with {pagename}")
+    title = quote(f"[doc] Documentation issue in '{pagename}'")
     labels = quote("area: Documentation")
     body = quote(
         dedent(
             f"""\
+    **Describe the bug**
+
     << Please describe the issue here >>
+    << You may also want to update the automatically generated issue title above. >>
 
     **Environment**
 

doc/_templates/breadcrumbs.html

@@ -23,6 +23,12 @@
       {% if vcs_blob_url %}
         <a href="{{ vcs_blob_url }}" class="fa fa-github"> {{ _('Open on GitHub') }}</a>
       {% endif %}
+      {%- set git_last_updated, sha1 = pagename | git_info | default((None, None), true) %}
+      {%- if sha1 %}
+        <a href="{{ pagename | vcs_link_get_open_issue_url(sha1) }}" class="fa fa-bug">
+          {{ _('Report an issue')}}
+        </a>
+      {% endif %}
     {% endif %}
   </li>
 {%- endblock %}

doc/_templates/footer.html

@@ -0,0 +1,30 @@
+{% extends "!footer.html" %}
+{% block contentinfo %}
+<p>
+  {%- if show_copyright %}
+  &#169; Copyright {{ copyright }}.
+  {%- endif %}
+
+  {%- if last_updated %}
+  <span class="lastupdated">
+    Last generated on {{ last_updated }}.
+  </span>
+  {%- endif -%}
+</p>
+{%- set git_last_updated, sha1 = pagename | git_info | default((None, None), true) %}
+{%- if git_last_updated %}
+<div class="admonition tip">
+  <p class="admonition-title">
+    Help us keep our technical documentation accurate and up-to-date!
+  </p>
+  <p>
+    The human-authored contents on this page was last updated on {{ git_last_updated }}.
+  </p>
+  <p>
+    If you find any errors on this page, outdated information, or have any other suggestion for
+    improving its contents, please consider
+    <a href="{{ pagename | vcs_link_get_open_issue_url(sha1) }}">opening an issue</a>.
+  </p>
+</div>
+{%- endif %}
+{% endblock %}

doc/conf.py

@@ -84,6 +84,7 @@ extensions = [
     "zephyr.doxyrunner",
     "zephyr.vcs_link",
     "zephyr.manifest_projects_table",
+    "zephyr.git_info",
     "notfound.extension",
     "sphinx_copybutton",
     "sphinx_togglebutton",