Sync documentation assets with templates (#104)

We have assembled a collection of reusable project assets:
https://github.com/arduino/tooling-project-assets
These assets will be used in the repositories of all Arduino tooling projects.

Some significant improvements and standardizations have been made in the upstream "template" website assets, and those
are introduced to this repository here.

Notable:

- Streamline website versioning system
- Update website dependencies
- Bump Python version used by the workflow from 3.8 to 3.9

Some tasks have changed:

- `docs:gen:commands` -> `go:cli-docs`
- `docs:publish` -> removed

Author: per1234

.github/workflows/publish-docs.yaml renamed to .github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml

@@ -1,24 +1,29 @@
-name: publish-docs
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md
+name: Deploy Website
+
+env:
+  # See: https://github.com/actions/setup-python/tree/v2#available-versions-of-python
+  PYTHON_VERSION: "3.9"
 
 on:
   push:
     branches:
-      # Branch to base "dev" website on. Set in build.py also.
+      # Branch to base "dev" website on. Set in siteversion.py also.
       - main
-      # release branches have names like 0.8.x, 0.9.x, ...
+      # Release branches have names like 0.8.x, 0.9.x, ...
       - "[0-9]+.[0-9]+.x"
     paths:
       - "docs/**"
-      - "docsgen/**"
-      - "cli/**"
-      - ".github/workflows/publish-docs.ya?ml"
+      - ".github/workflows/deploy-cobra-mkdocs-versioned-poetry.ya?ml"
+      - "go.mod"
+      - "go.sum"
       - "Taskfile.ya?ml"
+      - "**.go"
+      - "docsgen/**"
       - "mkdocs.ya?ml"
       - "poetry.lock"
       - "pyproject.toml"
-      - "go.mod"
-      - "go.sum"
-  # Run on branch or tag creation (will be filtered by the publish-determination job)
+  # Run on branch or tag creation (will be filtered by the publish-determination job).
   create:
 
 jobs:
@@ -38,44 +43,52 @@ jobs:
           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
+      - 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: Setup Go
-        uses: actions/setup-go@v2
-        with:
-          go-version: "1.16"
-
       - name: Install Python
         uses: actions/setup-python@v2
         with:
-          python-version: "3.8"
+          python-version: ${{ env.PYTHON_VERSION }}
 
-      - name: Install Python dependencies
+      - name: Install Poetry
         run: |
           python -m pip install --upgrade pip
           python -m pip install poetry
 
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Create all generated documentation content
+        run: task docs:generate
+
       - name: Install Python dependencies
         run: poetry install --no-root
 
-      - name: Publish docs
-        # 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.
+      - name: Determine versioning parameters
+        id: determine-versioning
+        run: echo "::set-output name=data::$(poetry run python docs/siteversion/siteversion.py)"
+
+      - name: Publish documentation
+        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
+          poetry run mike deploy \
+            --update-aliases \
+            --push \
+            --remote origin \
+            ${{ fromJson(steps.determine-versioning.outputs.data).version }} \
+            ${{ fromJson(steps.determine-versioning.outputs.data).alias }}

.gitignore

@@ -15,4 +15,4 @@ __pycache__/
 /site/
 /docsgen/arduino-fwuploader
 /docsgen/arduino-fwuploader.exe
-/docs/commands/*.md
+/docs/commands/

README.md

@@ -4,7 +4,7 @@ The Arduino Firmware Uploader is a tool made to update the firmware and/or add S
 equipped with WINC or NINA Wi-Fi module.
 
 [![tests-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml)
-[![docs-badge]](https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml)
+[![Deploy Website status](https://github.com/arduino/arduino-fwuploader/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/arduino/arduino-fwuploader/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml)
 
 ## ❗❗❗Notice regarding versions before 2.0.0 ❗❗❗
 
@@ -29,7 +29,6 @@ and report the bug to our Security Team 🛡️ Thank you!
 e-mail contact: [email protected]
 
 [tests-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/test.yaml/badge.svg
-[docs-badge]: https://github.com/arduino/arduino-fwuploader/actions/workflows/publish-docs.yaml/badge.svg
 [security policy]: https://github.com/arduino/arduino-fwuploader/security/policy
 [user documentation]: https://arduino.github.io/arduino-fwuploader/
 [install]: https://arduino.github.io/arduino-fwuploader/latest/installation

Taskfile.yml

@@ -14,33 +14,18 @@ tasks:
     desc: Run website locally
     deps:
       - task: poetry:install-deps
-      - task: docs:gen:commands
+      - task: docs:generate
     cmds:
       - poetry run mkdocs serve
 
-  docs:publish:
-    desc: Use Mike to build and push versioned docs
-    deps:
-      - docs:gen:commands
-    cmds:
-      - poetry run mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}}
-
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml
   docs:generate:
     desc: Create all generated documentation content
     deps:
-      - task: docs:gen:commands
-
-  docs:gen:commands:
-    desc: Generate command reference files
-    dir: ./docsgen
+      - task: go:cli-docs
     cmds:
-      # docs will generate examples using os.Args[0] so we need to call
-      # the generator `arduino-fwuploader`
-      - go build -o {{.PROJECT_NAME}}{{exeExt}}
-      # we invoke `arduino-fwuploader` like this instead of `./arduino-fwuploader` to remove
-      # the `./` chars from the examples
-      - PATH=. {{.PROJECT_NAME}} ../docs/commands
-      - task: docs:format
+      # Make the formatting consistent with the non-generated Markdown
+      - task: general:format-prettier
 
   docs:check:
     desc: Run documentation linting
@@ -55,11 +40,27 @@ tasks:
   docs:build:
     desc: Build documentation website contents
     deps:
-      - docs:gen:commands
+      - docs:generate
       - poetry:install-deps
     cmds:
       - poetry run mkdocs build -s
 
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-prettier-formatting-task/Taskfile.yml
+  general:format-prettier:
+    desc: Format all supported files with Prettier
+    cmds:
+      - npx prettier --write .
+
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml
+  go:cli-docs:
+    desc: Generate command line interface reference documentation
+    dir: ./docsgen
+    cmds:
+      # Command examples use os.Args[0] so the docs generation binary must have the same filename as the project
+      - go build -o {{.PROJECT_NAME}}{{exeExt}}
+      # The binary is invoked like this instead of `./{{.PROJECT_NAME}}` to remove the `./` chars from the examples
+      - PATH=. {{.PROJECT_NAME}} ../docs/commands
+
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml
   go:lint:
     desc: Lint Go code
@@ -245,6 +246,3 @@ vars:
     '
   # check-lint vars
   PRETTIER: [email protected]
-  DOCS_VERSION: dev
-  DOCS_ALIAS: ""
-  DOCS_REMOTE: "origin"

docs/commands/.gitkeep

@@ -1,5 +1,5 @@
 # Source:
-# https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-mkdocs-versioned/build/build.py
+# https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-mkdocs-versioned/siteversion/siteversion.py
 
 # Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
 
@@ -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,19 +39,20 @@
 
 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):
     """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, ...
     """
@@ -70,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, "..", "..")
@@ -84,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
-
-    # 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
+    # Deduce docs version from current branch.
+    versioning_data = get_docs_version(repo.active_branch.name, rel_br_names)
 
-    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
+#         $python siteversion.py
 #
 if __name__ == "__main__":
-    sys.exit(main())
+    main()

docs/build/build.py renamed to docs/siteversion/siteversion.py

@@ -0,0 +1,11 @@
+// Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/cobra/docsgen/go.mod
+module github.com/arduino/arduino-fwuploader/docsgen
+
+go 1.16
+
+replace github.com/arduino/arduino-fwuploader => ../
+
+require (
+	github.com/arduino/arduino-fwuploader v0.0.0
+	github.com/spf13/cobra v1.1.3
+)