vimhelp: Better header/footer and metadata on the web page

Add support for specifying the version and commit on the command line.

The footer will now show something that's more specific to MacVim, while
still leaving attribution for vimhelp with a link. It will show the
timestamp for generation time and the commit the docs were generated
from, so that a viewer can know easily whether the docs are up-to-date,
which it should be unless CI broke.

The navigation menu on top and bottom now also has a "MacVim reference"
to quickly navigate to `gui_mac.txt`, since that's likely the reason for
someone browsing this to begin with (instead of vanilla Vim's
documentation).

Author: ychin

vimhelp/scripts/h2h.py

@@ -52,6 +52,14 @@ def main():
         choices=("light", "dark"),
         help="Color theme (default: OS-native)",
     )
+    parser.add_argument(
+        "--version",
+        help="The version of Vim this document was generated from",
+    )
+    parser.add_argument(
+        "--commit",
+        help="The commit of Vim this document was generated from",
+    )
     parser.add_argument(
         "--no-tags",
         "-T",
@@ -99,14 +107,14 @@ def run(args):
 
     if not args.no_tags and (tags_file := args.in_dir / "tags").is_file():
         print("Processing tags file...")
-        h2h = VimH2H(mode=mode, project=args.project, tags=tags_file.read_text())
+        h2h = VimH2H(mode=mode, project=args.project, version=args.version, commit=args.commit, tags=tags_file.read_text())
         faq = args.in_dir / "vim_faq.txt"
         if faq.is_file():
             print("Processing FAQ tags...")
             h2h.add_tags(faq.name, faq.read_text())
     else:
         print("Initializing tags...")
-        h2h = VimH2H(mode=mode, project=args.project)
+        h2h = VimH2H(mode=mode, project=args.project, version=args.version, commit=args.commit)
         for infile in args.in_dir.iterdir():
             if infile.suffix == ".txt":
                 h2h.add_tags(infile.name, infile.read_text())

vimhelp/templates/page.html

@@ -50,7 +50,7 @@ <h1>{{project.name}} help files</h1>
 {{theme_switcher}}
 </div>
 <p>This is an HTML version of the <a href="{{project.url}}" target="_blank" rel="noopener noreferrer">{{project.name}}</a> help pages{% if version %}, current as of {{project.name}} {{version}}{% endif %}.
-They are kept up-to-date <a href="https://github.com/c4rlo/vimhelp" target="_blank" rel="noopener noreferrer" class="d">automatically</a>
+They are kept up-to-date <a href="https://github.com/macvim-dev/docs" target="_blank" rel="noopener noreferrer" class="d">automatically</a>
 from the <a href="{{project.doc_src_url}}" target="_blank" rel="noopener noreferrer" class="d">{{project.name}} source repository</a>.
 {% if project.name == "Vim" %}
 Also included is the <a href="vim_faq.txt.html">Vim FAQ</a>, kept up to date from its
@@ -65,6 +65,7 @@ <h1>{{project.name}} help files</h1>
 {% set sitenavi %}
 Quick links:
 <a href="{{helptxt}}">help overview</a> &middot;
+<a href="gui_mac.txt.html">MacVim reference</a> &middot;
 <a href="quickref.txt.html">quick reference</a> &middot;
 <a href="usr_toc.txt.html">user manual toc</a> &middot;
 <a href="{{helptxt}}#reference_toc">reference manual toc</a>
@@ -110,6 +111,7 @@ <h1>{{project.name}} help files</h1>
 </div>
 </main>
 <p>{{sitenavi}}</p>
-<footer>This site is maintained by Carlo Teubner (<i>(my first name) at cteubner dot net</i>).</footer>
+<footer>Generated at <span style="font-family:monospace;">{{current_time}}</span>{% if commit %} from commit <a href={{project.repo}}commit/{{commit}} style="font-family:monospace;">{{commit[:8]}}</a>{% endif %}. This documentation is maintained by <a href=https://github.com/macvim-dev>macvim-dev</a>.
+The code was modified from <a href=https://github.com/c4rlo/vimhelp>vimhelp</a> (made by Carlo Teubner).</footer>
 </body>
 </html>

vimhelp/vimhelp/vimh2h.py

@@ -1,5 +1,6 @@
 # Translates Vim documentation to HTML
 
+from datetime import datetime
 import flask
 import functools
 import html
@@ -155,10 +156,11 @@ def fix_tabs(self, text):
 
 
 class VimH2H:
-    def __init__(self, mode="online", project="vim", version=None, tags=None):
+    def __init__(self, mode="online", project="vim", version=None, tags=None, commit=None):
         self._mode = mode
         self._project = PROJECTS[project]
         self._version = version
+        self._commit = commit
         self._urls = {}
         if tags is not None:
             for line in RE_NEWLINE.split(tags):
@@ -339,6 +341,8 @@ def to_html(self, filename, contents):
         static_dir = "/" if self._mode == "online" else ""
         helptxt = "./" if self._mode == "online" else "index.html"
 
+        current_time = datetime.utcnow().strftime("%Y-%m-%d %H:%M:%SZ")
+
         return flask.render_template(
             "page.html",
             mode=self._mode,
@@ -349,6 +353,8 @@ def to_html(self, filename, contents):
             helptxt=helptxt,
             content=flask.Markup("".join(out)),
             sidebar_headings=sidebar_headings,
+            current_time=current_time,
+            commit=self._commit,
         )