From 1b6ee04deff889b92212d9ddb1653f1ffde3dc47 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Mon, 3 Dec 2018 14:52:24 -0500 Subject: [PATCH] use git modification timestamps as last-updated time for each page Look at the git history to determine the last time a page was modified and use that date as the last-updated date instead of the default value of the current time. Change-Id: I80db00eb2016859e1095c6a1db952f17df3e00d6 Signed-off-by: Doug Hellmann --- openstackdocstheme/__init__.py | 8 +- openstackdocstheme/page_context.py | 94 +++++++++++++++++++ .../theme/openstackdocs/layout.html | 4 +- ...last-updated-via-git-245fb14be3770a19.yaml | 6 ++ 4 files changed, 109 insertions(+), 3 deletions(-) create mode 100644 openstackdocstheme/page_context.py create mode 100644 releasenotes/notes/last-updated-via-git-245fb14be3770a19.yaml diff --git a/openstackdocstheme/__init__.py b/openstackdocstheme/__init__.py index bc1e98b..730e8e1 100644 --- a/openstackdocstheme/__init__.py +++ b/openstackdocstheme/__init__.py @@ -12,5 +12,11 @@ # License for the specific language governing permissions and limitations # under the License. -from .ext import setup # noqa +from . import ext # noqa +from . import page_context # noqa from .paths import * # noqa + + +def setup(app): + ext.setup(app) + page_context.setup(app) diff --git a/openstackdocstheme/page_context.py b/openstackdocstheme/page_context.py new file mode 100644 index 0000000..db71400 --- /dev/null +++ b/openstackdocstheme/page_context.py @@ -0,0 +1,94 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. + +import datetime +import os.path +import subprocess + +from sphinx.util import logging + +LOG = logging.getLogger(__name__) + +_default_last_updated = datetime.datetime.now() + + +def _get_last_updated_file(src_file): + if not os.path.exists(src_file): + return None + try: + last_updated_t = subprocess.check_output( + [ + 'git', 'log', '-n1', '--format=%ad', + '--date=format:%Y-%m-%d %H:%M:%S', + '--', src_file, + ] + ).decode('utf-8').strip() + except subprocess.CalledProcessError as err: + LOG.info( + '[openstackdocstheme] Could not get modification time of %s: %s', + src_file, err) + else: + if last_updated_t: + try: + return datetime.datetime.strptime(last_updated_t, + '%Y-%m-%d %H:%M:%S') + except ValueError as err: + LOG.info( + '[openstackdocstheme] ' + 'Could not parse modification time of %s: %r', + src_file, last_updated_t) + return None + + +def _get_last_updated(app, pagename): + last_updated = None + full_src_file = app.builder.env.doc2path(pagename) + + candidates = [] + + # Strip the prefix from the filename so the git command recognizes + # the file as part of the current repository. + src_file = full_src_file[len(app.builder.env.srcdir):].lstrip('/') + candidates.append(src_file) + + if not os.path.exists(src_file): + # Some of the files are in doc/source and some are not. Some + # of the ones that are not are symlinked. If we can't find the + # file after stripping the full prefix, try looking for it in + # doc/source explicitly. + candidates.append(os.path.join('doc/source', src_file)) + + for filename in candidates: + last_updated = _get_last_updated_file(filename) + if last_updated: + LOG.info( + '[openstackdocstheme] Last updated for %s is %s', + pagename, last_updated) + return last_updated + LOG.info( + '[openstackdocstheme] could not determine last_updated for %r', + pagename) + return _default_last_updated + + +def html_page_context(app, pagename, templatename, context, doctree): + # Use the last modified date from git instead of applying a single + # value to the entire site. + context['last_updated'] = _get_last_updated(app, pagename) + + +def setup(app): + LOG.info('[openstackdocstheme] connecting html-page-context event handler') + app.connect('html-page-context', html_page_context) + return { + 'parallel_read_safe': True, + } diff --git a/openstackdocstheme/theme/openstackdocs/layout.html b/openstackdocstheme/theme/openstackdocs/layout.html index 1abf1c7..a183275 100644 --- a/openstackdocstheme/theme/openstackdocs/layout.html +++ b/openstackdocstheme/theme/openstackdocs/layout.html @@ -40,7 +40,7 @@ ga('send', 'pageview');
{% include 'titlerow.html' %}
-
updated: {{ last_updated }}
+
this page last updated: {{ last_updated }}
{%- block otherversions %} {%- if other_versions %}
@@ -74,7 +74,7 @@ ga('send', 'pageview'); {% endif %}
-
updated: {{ last_updated }}
+
this page last updated: {{ last_updated }}
diff --git a/releasenotes/notes/last-updated-via-git-245fb14be3770a19.yaml b/releasenotes/notes/last-updated-via-git-245fb14be3770a19.yaml new file mode 100644 index 0000000..8583425 --- /dev/null +++ b/releasenotes/notes/last-updated-via-git-245fb14be3770a19.yaml @@ -0,0 +1,6 @@ +--- +features: + - | + The "last-updated" page context for each page is set based on the + git history for the source document for the page. If there is no + source document checked into git, the current time is used.