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>
This commit is contained in:
parent
32cd631a1b
commit
701f59ee1e
5 changed files with 144 additions and 1 deletions
103
doc/_extensions/zephyr/git_info.py
Normal file
103
doc/_extensions/zephyr/git_info.py
Normal file
|
@ -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,
|
||||
}
|
|
@ -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**
|
||||
|
||||
|
|
6
doc/_templates/breadcrumbs.html
vendored
6
doc/_templates/breadcrumbs.html
vendored
|
@ -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 %}
|
||||
|
|
30
doc/_templates/footer.html
vendored
Normal file
30
doc/_templates/footer.html
vendored
Normal file
|
@ -0,0 +1,30 @@
|
|||
{% extends "!footer.html" %}
|
||||
{% block contentinfo %}
|
||||
<p>
|
||||
{%- if show_copyright %}
|
||||
© 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 %}
|
|
@ -84,6 +84,7 @@ extensions = [
|
|||
"zephyr.doxyrunner",
|
||||
"zephyr.vcs_link",
|
||||
"zephyr.manifest_projects_table",
|
||||
"zephyr.git_info",
|
||||
"notfound.extension",
|
||||
"sphinx_copybutton",
|
||||
"sphinx_togglebutton",
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue