Use website versioning helper script only for generating parameters

Determining the correct versioning parameters for the versioned website system is relatively complex. For this reason,
it's helpful to do this in a Python script, which provides a more capable framework for this code and its testing.

Previously, the system worked like this:

1. Repository event triggers workflow.
2. Workflow executes helper script.
3. Helper script executes task.
4. Task executes mike.

For me, this long chain of scripts, each in a different language, makes the system very difficult to understand and
maintain. Although the helper script is useful for determining the versioning parameters, executing a task is well within
the capabilities of a workflow. The process is run exclusively on GitHub Actions, with no reason to ever run it locally,
to there is no harm to basing significant amounts of it in the workflow. So it's better for the helper script to have a
single job and the workflow to act as the orchestrator of the tools.

Author: per1234

workflow-templates/assets/deploy-mkdocs-versioned/build/build.py

@@ -13,11 +13,9 @@
 # Arduino software without disclosing the source code of your own applications.
 # To purchase a commercial license, send an email to [email protected].
 import os
-import sys
 import re
-import subprocess
+import json
 
-import click
 from git import Repo
 
 # In order to provide support for multiple project releases, Documentation is versioned so that visitors can select
@@ -41,15 +39,15 @@
 
 def get_docs_version(ref_name, release_branches):
     if ref_name in DEV_BRANCHES:
-        return "dev", ""
+        return {"version": "dev", "alias": ""}
 
     if ref_name in release_branches:
         # if version is latest, add an alias
         alias = "latest" if ref_name == release_branches[0] else ""
         # strip `.x` suffix from the branch name to get the version: 0.3.x -> 0.3
-        return ref_name[:-2], alias
+        return {"version": ref_name[:-2], "alias": alias}
 
-    return None, None
+    return {"version": None, "alias": None}
 
 
 def get_rel_branch_names(blist):
@@ -71,10 +69,7 @@ def get_rel_branch_names(blist):
     return sorted(names, key=lambda x: int(x.split(".")[1]), reverse=True)
 
 
-@click.command()
-@click.option("--dry", is_flag=True)
-@click.option("--remote", default="origin", help="The git remote where to push.")
-def main(dry, remote):
+def main():
     # Detect repo root folder
     here = os.path.dirname(os.path.realpath(__file__))
     repo_dir = os.path.join(here, "..", "..")
@@ -85,26 +80,16 @@ def main(dry, remote):
     # Get the list of release branch names
     rel_br_names = get_rel_branch_names(repo.refs)
 
-    # Deduce docs version from current branch. Use the 'latest' alias if
-    # version is the most recent
-    docs_version, alias = get_docs_version(repo.active_branch.name, rel_br_names)
-    if docs_version is None:
-        print(f"Can't get version from current branch '{repo.active_branch}', skip docs generation")
-        return 0
+    # Deduce docs version from current branch.
+    versioning_data = get_docs_version(repo.active_branch.name, rel_br_names)
 
-    # Taskfile args aren't regular args so we put everything in one string
-    cmd = (f"task docs:publish DOCS_REMOTE={remote} DOCS_VERSION={docs_version} DOCS_ALIAS={alias}",)
-
-    if dry:
-        print(cmd)
-        return 0
-
-    subprocess.run(cmd, shell=True, check=True, cwd=repo_dir)
+    # Return the data as JSON on stdout
+    print(json.dumps(versioning_data))
 
 
 # Usage:
 #     To run the script (must be run from within the repo tree):
 #         $python build.py
 #
 if __name__ == "__main__":
-    sys.exit(main())
+    main()

workflow-templates/assets/deploy-mkdocs-versioned/build/tests/test_all.py

@@ -16,18 +16,18 @@
 
 
 def test_get_docs_version():
-    ver, alias = build.get_docs_version("main", [])
-    assert ver == "dev"
-    assert alias == ""
+    data = build.get_docs_version("main", [])
+    assert data["version"] == "dev"
+    assert data["alias"] == ""
 
     release_names = ["1.4.x", "0.13.x"]
-    ver, alias = build.get_docs_version("0.13.x", release_names)
-    assert ver == "0.13"
-    assert alias == ""
-    ver, alias = build.get_docs_version("1.4.x", release_names)
-    assert ver == "1.4"
-    assert alias == "latest"
+    data = build.get_docs_version("0.13.x", release_names)
+    assert data["version"] == "0.13"
+    assert data["alias"] == ""
+    data = build.get_docs_version("1.4.x", release_names)
+    assert data["version"] == "1.4"
+    assert data["alias"] == "latest"
 
-    ver, alias = build.get_docs_version("0.1.x", [])
-    assert ver is None
-    assert alias is None
+    data = build.get_docs_version("0.1.x", [])
+    assert data["version"] is None
+    assert data["alias"] is None

workflow-templates/dependabot/workflow-template-copies/.github/workflows/deploy-mkdocs-versioned-poetry.yml

@@ -64,11 +64,18 @@ jobs:
       - name: Install Python dependencies
         run: poetry install --no-root
 
+      - name: Determine versioning parameters
+        id: determine-versioning
+        run: echo "::set-output name=data::$(poetry run python docs/build/build.py)"
+
       - name: Publish documentation
-        # Determine docs version for the commit pushed and publish accordingly using Mike.
-        # Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits.
+        if: fromJson(steps.determine-versioning.outputs.data).version != null
         run: |
+          # Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits.
           git config --global user.email "[email protected]"
           git config --global user.name "ArduinoBot"
           git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
-          poetry run python docs/build/build.py
+          task docs:publish \
+            DOCS_REMOTE=origin \
+            DOCS_VERSION=${{ fromJson(steps.determine-versioning.outputs.data).version }} \
+            DOCS_ALIAS=${{ fromJson(steps.determine-versioning.outputs.data).alias }}

workflow-templates/deploy-mkdocs-versioned-poetry.md

@@ -70,7 +70,7 @@ See the ["Deploy Website" workflow (MkDocs, Poetry) documentation](deploy-mkdocs
 
 1. Run this command:
    ```
-   poetry add --dev "click@<7.2" "gitpython@^3.1.1" "mike@^1.0.1"
+   poetry add --dev "gitpython@^3.1.1" "mike@^1.0.1"
    ```
 1. Commit the resulting `pyproject.toml` and `poetry.lock` files.
 

workflow-templates/deploy-mkdocs-versioned-poetry.yml

@@ -64,11 +64,18 @@ jobs:
       - name: Install Python dependencies
         run: poetry install --no-root
 
+      - name: Determine versioning parameters
+        id: determine-versioning
+        run: echo "::set-output name=data::$(poetry run python docs/build/build.py)"
+
       - name: Publish documentation
-        # Determine docs version for the commit pushed and publish accordingly using Mike.
-        # Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits.
+        if: fromJson(steps.determine-versioning.outputs.data).version != null
         run: |
+          # Publishing implies creating a git commit on the gh-pages branch, we let @ArduinoBot own these commits.
           git config --global user.email "[email protected]"
           git config --global user.name "ArduinoBot"
           git fetch --no-tags --prune --depth=1 origin +refs/heads/gh-pages:refs/remotes/origin/gh-pages
-          poetry run python docs/build/build.py
+          task docs:publish \
+            DOCS_REMOTE=origin \
+            DOCS_VERSION=${{ fromJson(steps.determine-versioning.outputs.data).version }} \
+            DOCS_ALIAS=${{ fromJson(steps.determine-versioning.outputs.data).alias }}