Merge pull request #45 from per1234/versioned-mkdocs

Add template for versioned MkDocs website generation system

Author: per1234

workflow-templates/assets/deploy-mkdocs-versioned/Taskfile.yml

@@ -0,0 +1,13 @@
+version: "3"
+
+vars:
+  DOCS_VERSION: dev
+  DOCS_ALIAS: ""
+  DOCS_REMOTE: "origin"
+
+tasks:
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-mkdocs-versioned/Taskfile.yml
+  docs:publish:
+    desc: Use Mike to build and push versioned docs
+    cmds:
+      - poetry run mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}}

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

@@ -0,0 +1,140 @@
+# Source:
+# https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-mkdocs-versioned/build.py
+
+# Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
+
+# This software is released under the GNU General Public License version 3
+# The terms of this license can be found at:
+# https://www.gnu.org/licenses/gpl-3.0.en.html
+
+# You can be released from the requirements of the above licenses by purchasing
+# a commercial license. Buying such a license is mandatory if you want to
+# modify or otherwise use the software for commercial activities involving the
+# 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 unittest
+import subprocess
+
+import click
+from git import Repo
+
+# In order to provide support for multiple project releases, Documentation is versioned so that visitors can select
+# which version of the documentation website should be displayed. Unfortunately this feature isn't provided by GitHub
+# pages or MkDocs, so we had to implement it on top of the generation process.
+#
+# - A special version of the documentation called `dev` is provided to reflect the status of the project on the
+#   default branch - this includes unreleased features and bugfixes.
+# - Docs are versioned after the minor version of a release. For example, release version `0.99.1` and
+#   `0.99.2` will be both covered by documentation version `0.99`.
+#
+# The CI is responsible for guessing which version of the project we're building docs for, so that generated content
+# will be stored in the appropriate section of the documentation website. Because this guessing might be fairly complex,
+# the logic is implemented in this Python script. The script will determine the version of the project that was
+# modified in the current commit (either `dev` or an official, numbered release) and whether the redirect to the latest
+# version that happens on the landing page should be updated or not.
+
+
+DEV_BRANCHES = ["main"]  # Name of the branch used for the "dev" website source content
+
+
+class TestScript(unittest.TestCase):
+    def test_get_docs_version(self):
+        ver, alias = get_docs_version("main", [])
+        self.assertEqual(ver, "dev")
+        self.assertEqual(alias, "")
+
+        release_names = ["1.4.x", "0.13.x"]
+        ver, alias = get_docs_version("0.13.x", release_names)
+        self.assertEqual(ver, "0.13")
+        self.assertEqual(alias, "")
+        ver, alias = get_docs_version("1.4.x", release_names)
+        self.assertEqual(ver, "1.4")
+        self.assertEqual(alias, "latest")
+
+        ver, alias = get_docs_version("0.1.x", [])
+        self.assertIsNone(ver)
+        self.assertIsNone(alias)
+
+
+def get_docs_version(ref_name, release_branches):
+    if ref_name in DEV_BRANCHES:
+        return "dev", ""
+
+    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 None, None
+
+
+def get_rel_branch_names(blist):
+    """Get the names of the release branches, sorted from newest to older.
+
+    Only process remote refs so we're sure to get all of them and clean up the
+    name so that we have a list of strings like 0.6.x, 0.7.x, ...
+    """
+    pattern = re.compile(r"origin/(\d+\.\d+\.x)")
+    names = []
+    for b in blist:
+        res = pattern.search(b.name)
+        if res is not None:
+            names.append(res.group(1))
+
+    # Since sorting is stable, first sort by major...
+    names = sorted(names, key=lambda x: int(x.split(".")[0]), reverse=True)
+    # ...then by minor
+    return sorted(names, key=lambda x: int(x.split(".")[1]), reverse=True)
+
+
+@click.command()
+@click.option("--test", is_flag=True)
+@click.option("--dry", is_flag=True)
+@click.option("--remote", default="origin", help="The git remote where to push.")
+def main(test, dry, remote):
+    # Run tests if requested
+    if test:
+        unittest.main(argv=[""], exit=False)
+        sys.exit(0)
+
+    # Detect repo root folder
+    here = os.path.dirname(os.path.realpath(__file__))
+    repo_dir = os.path.join(here, "..")
+
+    # Get current repo
+    repo = Repo(repo_dir)
+
+    # 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
+
+    # 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)
+
+
+# Usage:
+#
+#     To run the tests:
+#         $python build.py --test
+#
+#     To run the script (must be run from within the repo tree):
+#         $python build.py
+#
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,82 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/deploy-mkdocs-versioned-poetry.md
+name: Deploy Website
+
+on:
+  push:
+    branches:
+      # Branch to base "dev" website on. Set in build.py also.
+      - main
+      # Release branches have names like 0.8.x, 0.9.x, ...
+      - "[0-9]+.[0-9]+.x"
+    paths:
+      - "docs/**"
+      - ".github/workflows/deploy-mkdocs-versioned-poetry.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+  # Run on branch or tag creation (will be filtered by the publish-determination job).
+  create:
+
+jobs:
+  publish-determination:
+    runs-on: ubuntu-latest
+    outputs:
+      result: ${{ steps.determination.outputs.result }}
+    steps:
+      - name: Determine if documentation should be published on this workflow run
+        id: determination
+        run: |
+          RELEASE_BRANCH_REGEX="refs/heads/[0-9]+.[0-9]+.x"
+          if [[ "${{ github.event_name }}" == "push" || ( "${{ github.event_name }}" == "create" && "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX ) ]]; then
+            RESULT="true"
+          else
+            RESULT="false"
+          fi
+
+          echo "::set-output name=result::$RESULT"
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: publish-determination
+    if: needs.publish-determination.outputs.result == 'true'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Taskfile
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.9"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Poetry
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install poetry
+
+      - name: Install Python dependencies
+        run: poetry install --no-root
+
+      - 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.
+        run: |
+          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.py