From ba4e9ff00440e0376661b36da928d3d69399011e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rimas=20Misevi=C4=8Dius?= Date: Tue, 31 Oct 2023 19:50:13 +0200 Subject: [PATCH] Automate the creation of documentation versions * Create documentation versions on `git push --tags` * Automate updates to versions.txt (documentation versions) --- .github/workflows/documentation.yml | 16 ++++--- .gitignore | 1 + Doxyfile | 2 +- doc/common/version-select.js | 4 +- doc/common/versions.txt | 1 - tools/update-docs-versions.py | 68 +++++++++++++++++++++++++++++ 6 files changed, 83 insertions(+), 9 deletions(-) delete mode 100644 doc/common/versions.txt create mode 100755 tools/update-docs-versions.py diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 9aca97fa..67322585 100644 --- a/.github/workflows/documentation.yml +++ b/.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 }} diff --git a/.gitignore b/.gitignore index f83adeee..91d37db6 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ # generated documentation /doc/html/ /doc/theme/ +/doc/versions.txt # downloadable tests directory /test/wpt/ diff --git a/Doxyfile b/Doxyfile index 3cfd9e6f..ba37dd00 100644 --- a/Doxyfile +++ b/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 diff --git a/doc/common/version-select.js b/doc/common/version-select.js index feeb1e3f..a4263a38 100644 --- a/doc/common/version-select.js +++ b/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"); diff --git a/doc/common/versions.txt b/doc/common/versions.txt deleted file mode 100644 index ba2906d0..00000000 --- a/doc/common/versions.txt +++ /dev/null @@ -1 +0,0 @@ -main diff --git a/tools/update-docs-versions.py b/tools/update-docs-versions.py new file mode 100755 index 00000000..f404e053 --- /dev/null +++ b/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: {} \n" + .format(os.path.basename(__file__)), + file=sys.stderr)