Sync documentation assets with templates

.github/workflows/publish-docs.yaml → .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/build/build.py → docs/siteversion/siteversion.py

@@ -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()

docsgen/go.mod

@@ -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
+)