Automate the creation of documentation versions

* Create documentation versions on `git push --tags`

* Automate updates to versions.txt (documentation versions)

.github/workflows/documentation.yml

@@ -12,9 +12,10 @@ jobs:
     concurrency:
       group: ${{ github.workflow }}-${{ github.ref }}
     env:
-      upa_deploy: ${{ github.ref == 'refs/heads/main' || '' }}
+      upa_deploy: ${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') || '' }}
       upa_docs_repository: upa-url/docs
-      upa_docs_dir: main
+      # Used in Doxyfile: PROJECT_NUMBER = $(UPA_DOCS_VERSION)
+      UPA_DOCS_VERSION: ${{ github.ref_name }}
     steps:
       - uses: actions/checkout@v4
       - name: Download theme
@@ -33,11 +34,16 @@ jobs:
           ref: gh-pages
           path: build-docs
 
-      - name: Prepare directory for publication
+      - name: Update versions.txt
         if: env.upa_deploy
         run: |
-          sudo chown --recursive $USER doc/html
           mkdir -p build-docs
+          echo "upa_docs_dir=$(tools/update-docs-versions.py build-docs $GITHUB_REF)" >> "$GITHUB_ENV"
+
+      - name: Prepare directory for publication
+        if: env.upa_deploy && env.upa_docs_dir
+        run: |
+          sudo chown --recursive $USER doc/html
           rm -rf build-docs/.git
           rm -rf build-docs/common
           rm -rf build-docs/${{ env.upa_docs_dir }}
@@ -47,7 +53,7 @@ jobs:
 
       - name: Deploy to ${{ env.upa_docs_repository }}
         uses: JamesIves/github-pages-deploy-action@v4
-        if: env.upa_deploy
+        if: env.upa_deploy && env.upa_docs_dir
         with:
           ssh-key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
           repository-name: ${{ env.upa_docs_repository }}

.gitignore

@@ -8,6 +8,7 @@
 # generated documentation
 /doc/html/
 /doc/theme/
+/doc/versions.txt
 
 # downloadable tests directory
 /test/wpt/

Doxyfile

@@ -48,7 +48,7 @@ PROJECT_NAME           = "Upa URL C++ library"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = "0.0.1"
+PROJECT_NUMBER         = $(UPA_DOCS_VERSION)
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

doc/common/version-select.js

@@ -5,8 +5,8 @@
 (function () {
   // path segment to replace with version string
   const path_segment_ind = 2;
-  // versions.txt is in the same folder as this script
-  const versions_url = new URL("versions.txt", document.currentScript.src);
+  // versions.txt is in the parent folder of this script
+  const versions_url = new URL("../versions.txt", document.currentScript.src);
 
   window.addEventListener("DOMContentLoaded", event => {
     const list_ctl = document.getElementById("version-select");

tools/update-docs-versions.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+#
+# Copyright 2023 Rimas Misevičius
+# Distributed under the BSD-style license that can be
+# found in the LICENSE file.
+import os
+import re
+import sys
+
+version_regex = r"^v[0-9]+(\.[0-9]+)+$"
+
+def main(versions_folder, git_ref):
+    versions_path = os.path.join(versions_folder, "versions.txt")
+    if git_ref.startswith("refs/heads/"):
+        branch = git_ref[11:]
+        if branch == "main":
+            update_ver(versions_path, branch, branch)
+    elif git_ref.startswith("refs/tags/"):
+        version = git_ref[10:]
+        if re.match(version_regex, version):
+            version_pieces = version.split(".")
+            dir = ".".join(version_pieces[:2])
+            ver = ".".join(version_pieces)
+            update_ver(versions_path, dir, ver)
+
+def update_ver(versions_path, dir, ver):
+    dir_ver = dir if dir == ver else dir + ":" + ver
+    lines = []
+    if os.path.exists(versions_path):
+        with open(versions_path, "r") as file:
+            lines = file.read().splitlines()
+    found = False
+    for i in range(len(lines)):
+        if lines[i].split(":")[0] == dir:
+            lines[i] = dir_ver
+            found = True
+            break
+    if not found:
+        lines.append(dir_ver)
+    lines.sort(key=key_of_dir_ver)
+    # write result
+    with open(versions_path, 'w') as file:
+        for line in lines:
+            file.write(line + '\n')
+    print(dir)
+
+def key_of_dir_ver(dir_ver):
+    dir = dir_ver.split(":")[0]
+    if dir == "main":
+        return 0
+    # remove starting "v"
+    if dir.startswith("v"):
+        dir = dir[1:]
+    pieces = dir.split(".")
+    div = 1000000 * int(pieces[0])
+    if len(pieces) > 1:
+        div += 1000 * int(pieces[1])
+    if len(pieces) > 2:
+        div += int(pieces[2])
+    return 1 / div
+
+if __name__ == "__main__":
+    if len(sys.argv) == 3:
+        main(sys.argv[1], sys.argv[2])
+    else:
+        print("Usage: {} <directory of versions.txt file> <git ref>\n"
+            .format(os.path.basename(__file__)),
+            file=sys.stderr)