[skip changelog] Sync documentation assets with templates

.github/workflows/check-markdown-task.yml

@@ -0,0 +1,87 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-markdown-task.md
+name: Check Markdown
+
+env:
+  # See: https://github.com/actions/setup-go/tree/v2#readme
+  GO_VERSION: "1.16"
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    paths:
+      - ".github/workflows/check-markdown-task.ya?ml"
+      - ".markdown-link-check.json"
+      - "Taskfile.ya?ml"
+      - "**/.markdownlint*"
+      - "**.go"
+      - "**.mdx?"
+      - "**.mkdn"
+      - "**.mdown"
+      - "**.markdown"
+      - "rpc/**"
+  pull_request:
+    paths:
+      - ".github/workflows/check-markdown-task.ya?ml"
+      - ".markdown-link-check.json"
+      - "Taskfile.ya?ml"
+      - "**/.markdownlint*"
+      - "**.go"
+      - "**.mdx?"
+      - "**.mkdn"
+      - "**.mdown"
+      - "**.markdown"
+      - "rpc/**"
+  schedule:
+    # Run every Tuesday at 8 AM UTC to catch breakage caused by external changes.
+    - cron: "0 8 * * TUE"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Initialize markdownlint-cli problem matcher
+        uses: xt0rted/markdownlint-problem-matcher@v1
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Lint
+        run: task markdown:lint
+
+  links:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Install Go dependencies
+        run: go install github.com/pseudomuto/protoc-gen-doc/cmd/[email protected]
+
+      - name: Install protoc compiler
+        uses: arduino/setup-protoc@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Check links
+        run: task --silent markdown:check-links

.github/workflows/check-mkdocs-task.yml

@@ -0,0 +1,67 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-mkdocs-task.md
+name: Check Website
+
+env:
+  # See: https://github.com/actions/setup-go/tree/v2#readme
+  GO_VERSION: "1.16"
+  # See: https://github.com/actions/setup-python/tree/v2#available-versions-of-python
+  PYTHON_VERSION: "3.9"
+
+# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
+on:
+  push:
+    paths:
+      - ".github/workflows/check-mkdocs-task.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  pull_request:
+    paths:
+      - ".github/workflows/check-mkdocs-task.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Install Go dependencies
+        run: go install github.com/pseudomuto/protoc-gen-doc/cmd/[email protected]
+
+      - name: Install protoc compiler
+        uses: arduino/setup-protoc@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install Poetry
+        run: pip install poetry
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Build website
+        run: task website:check

.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml

@@ -0,0 +1,110 @@
+# 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-go/tree/v2#readme
+  GO_VERSION: "1.16"
+  # 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 siteversion.py also.
+      - master
+      # Release branches have names like 0.8.x, 0.9.x, ...
+      - "[0-9]+.[0-9]+.x"
+    paths:
+      - "docs/**"
+      - ".github/workflows/deploy-cobra-mkdocs-versioned-poetry.ya?ml"
+      - "go.mod"
+      - "go.sum"
+      - "Taskfile.ya?ml"
+      - "**.go"
+      - "docsgen/**"
+      - "rpc/**"
+      - "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 Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: ${{ env.GO_VERSION }}
+
+      - name: Install Go dependencies
+        run: go install github.com/pseudomuto/protoc-gen-doc/cmd/[email protected]
+
+      - name: Install protoc compiler
+        uses: arduino/setup-protoc@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - 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: 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 mike deploy \
+            --update-aliases \
+            --push \
+            --remote origin \
+            ${{ fromJson(steps.determine-versioning.outputs.data).version }} \
+            ${{ fromJson(steps.determine-versioning.outputs.data).alias }}

.gitignore

@@ -25,5 +25,6 @@ venv
 /site/
 /public/
 /docsgen/arduino-cli
+/docsgen/arduino-cli.exe
 /docs/rpc/*.md
 /docs/commands/*.md

markdown-link-check-config.json → .markdown-link-check.json

@@ -1,4 +1,7 @@
 {
+  "retryOn429": true,
+  "retryCount": 3,
+  "aliveStatusCodes": [200, 206],
   "ignorePatterns": [
     {
       "pattern": "https?://localhost:\\d*/"

.markdownlint.yml

@@ -0,0 +1,62 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown/.markdownlint.yml
+# See: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+# The code style defined in this file is the official standardized style to be used in all Arduino projects and should
+# not be modified.
+# Note: Rules disabled solely because they are redundant to Prettier are marked with a "Prettier" comment.
+
+default: false
+MD001: false
+MD002: false
+MD003: false # Prettier
+MD004: false # Prettier
+MD005: false # Prettier
+MD006: false # Prettier
+MD007: false # Prettier
+MD008: false # Prettier
+MD009:
+  br_spaces: 0
+  strict: true
+  list_item_empty_lines: false # Prettier
+MD010: false # Prettier
+MD011: true
+MD012: false # Prettier
+MD013: false
+MD014: false
+MD018: true
+MD019: false # Prettier
+MD020: true
+MD021: false # Prettier
+MD022: false # Prettier
+MD023: false # Prettier
+MD024: false
+MD025:
+  level: 1
+  front_matter_title: '^\s*"?title"?\s*[:=]'
+MD026: false
+MD027: false # Prettier
+MD028: false
+MD029:
+  style: one
+MD030:
+  ul_single: 1
+  ol_single: 1
+  ul_multi: 1
+  ol_multi: 1
+MD031: false # Prettier
+MD032: false # Prettier
+MD033: false
+MD034: false
+MD035: false # Prettier
+MD036: false
+MD037: true
+MD038: true
+MD039: true
+MD040: false
+MD041: false
+MD042: true
+MD043: false
+MD044: false
+MD045: true
+MD046:
+  style: fenced
+MD047: false # Prettier

README.md

@@ -7,7 +7,7 @@ and many other tools needed to use any Arduino compatible board and platform.
 
 [![tests-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=test)
 [![nightly-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=nightly)
-[![docs-badge]](https://github.com/Arduino/arduino-cli/actions?workflow=publish-docs)
+[![Deploy Website status](https://github.com/arduino/arduino-cli/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/arduino/arduino-cli/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml)
 [![codecov-badge]](https://codecov.io/gh/arduino/arduino-cli)
 
 > **Note:** this software is currently under active development: anything can change at any time, API and UI must be
@@ -20,9 +20,9 @@ For guidance on installation and development, see the [User documentation].
 ## Quickstart
 
 1. [Install] the Arduino CLI
-2. Follow the [Getting Started] guide to check out what the CLI can do
-3. Browse the [Commands reference] to see all the available commands
-4. Should you have an issue, read the [FAQ] page
+1. Follow the [Getting Started] guide to check out what the CLI can do
+1. Browse the [Commands reference] to see all the available commands
+1. Should you have an issue, read the [FAQ] page
 
 ## How to contribute
 

Taskfile.yml

@@ -4,73 +4,98 @@ includes:
   dist: ./DistTasks.yml
 
 tasks:
-  docs:gen:commands:
-    desc: Generate command reference files
-    dir: ./docsgen
-    cmds:
-      # docs will generate examples using os.Args[0] so we need to call
-      # the generator `arduino-cli`
-      - go build -o arduino-cli
-      # we invoke `arduino-cli` like this instead of `./arduino-cli` to remove
-      # the `./` chars from the examples
-      - PATH=. arduino-cli ../docs/commands
-      - task: general:format-prettier
-
   docs:gen:protobuf:
     desc: Generate markdown contents for protobuffers
     cmds:
       - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,commands.md --proto_path=rpc ./rpc/cc/arduino/cli/commands/v1/*.proto'
       - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,monitor.md --proto_path=rpc ./rpc/cc/arduino/cli/monitor/v1/*.proto'
       - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,settings.md --proto_path=rpc ./rpc/cc/arduino/cli/settings/v1/*.proto'
       - '{{ default "protoc" .PROTOC_BINARY }} --doc_out=./docs/rpc --doc_opt=markdown,debug.md --proto_path=rpc ./rpc/cc/arduino/cli/debug/v1/*.proto'
+
+  docs:generate:
+    desc: Create all generated documentation content
+    deps:
+      - task: go:cli-docs
+      - task: protoc:docs
+    cmds:
       - task: general:format-prettier
 
-  docs:gen:
-    desc: Generate documentation files
+  # 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:
-      - task: docs:gen:commands
-      - task: docs:gen:protobuf
+      - npx prettier --write .
 
-  docs:build:
-    desc: Build documentation website contents
-    deps:
-      - docs:gen:commands
-      - docs:gen:protobuf
+  # 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:
-      - mkdocs build -s
+      # 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
 
-  docs:publish:
-    desc: Use Mike to build and push versioned docs
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
+  markdown:check-links:
+    desc: Check for broken links
     deps:
-      - docs:gen:commands
-      - docs:gen:protobuf
+      - task: docs:generate
     cmds:
-      - mike deploy -u -p -r {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}}
+      - |
+        if [[ "{{.OS}}" == "Windows_NT" ]]; then
+          # npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
+          # so the Windows user is required to have markdown-link-check installed and in PATH.
+          if ! which markdown-link-check &>/dev/null; then
+            echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme"
+            exit 1
+          fi
+          # Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero
+          # exit status, but it's better to check all links before exiting.
+          set +o errexit
+          STATUS=0
+          # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
+          # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
+          # \ characters special treatment on Windows in an attempt to support them as path separators.
+          for file in $(find . -regex ".*[.]md"); do
+            markdown-link-check \
+              --quiet \
+              --config "./.markdown-link-check.json" \
+              "$file"
+            STATUS=$(( $STATUS + $? ))
+          done
+          exit $STATUS
+        else
+          npx --package=markdown-link-check --call='
+            STATUS=0
+            for file in $(find . -regex ".*[.]md"); do
+              markdown-link-check \
+                --quiet \
+                --config "./.markdown-link-check.json" \
+                "$file"
+              STATUS=$(( $STATUS + $? ))
+            done
+            exit $STATUS
+          '
+        fi
 
-  docs:serve:
-    desc: Run documentation website locally
-    deps:
-      - docs:build
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
+  markdown:fix:
+    desc: Automatically correct linting violations in Markdown files where possible
     cmds:
-      - mkdocs serve
+      - npx markdownlint-cli --fix "**/*.md"
 
-  docs:check-links:
-    desc: Verifies there are no dead links in documentation
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
+  markdown:lint:
+    desc: Check for problems in Markdown files
     cmds:
-      - |
-        npx -p markdown-link-check -c '
-        STATUS=0
-        for file in $(find docs -name "*.md") README.md test/README.md client_example/README.md; do
-          markdown-link-check -c markdown-link-check-config.json -q "$file"
-          STATUS=$(( $STATUS + $? ))
-        done
-        exit $STATUS'
+      - npx markdownlint-cli "**/*.md"
 
-  # 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
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/poetry-task/Taskfile.yml
+  poetry:install-deps:
+    desc: Install dependencies managed by Poetry
     cmds:
-      - npx prettier --write .
+      - poetry install --no-root
 
   protoc:
     desc: Lint, format and compile protobuf definitions
@@ -200,6 +225,24 @@ tasks:
       - git add -N ./i18n/data
       - git diff --exit-code ./i18n/data &> /dev/null || { cd ./i18n && rice embed-go; }
 
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml
+  website:check:
+    desc: Check whether the MkDocs-based website will build
+    deps:
+      - task: docs:generate
+      - task: poetry:install-deps
+    cmds:
+      - poetry run mkdocs build --strict
+
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml
+  website:serve:
+    desc: Run website locally
+    deps:
+      - task: docs:generate
+      - task: poetry:install-deps
+    cmds:
+      - poetry run mkdocs serve
+
 vars:
   PROJECT_NAME: "arduino-cli"
   DIST_DIR: "dist"
@@ -238,8 +281,3 @@ vars:
   GOLINTBIN:
     sh: go list -f {{"{{"}}".Target{{"}}"}}" golang.org/x/lint/golint
   GOLINTFLAGS: "-min_confidence 0.8 -set_exit_status"
-  # docs versioning
-  DOCS_VERSION: dev
-  DOCS_ALIAS: ""
-  DOCS_REMOTE: "origin"
-  PRETTIER: prettier@2.0.5

docs/CONTRIBUTING.md

@@ -123,15 +123,21 @@ task test-integration
 By default, all tests from all go packages are run. To run only unit tests from one or more specific packages, you can
 set the TARGETS environment variable, e.g.:
 
-    TARGETS=./arduino/cores/packagemanager task test-unit
+```
+TARGETS=./arduino/cores/packagemanager task test-unit
+```
 
 Alternatively, to run only some specific test(s), you can specify a regex to match against the test function name:
 
-    TEST_REGEX='^TestTryBuild.*' task test-unit
+```
+TEST_REGEX='^TestTryBuild.*' task test-unit
+```
 
 Both can be combined as well, typically to run only a specific test:
 
-    TEST_REGEX='^TestFindBoardWithFQBN$' TARGETS=./arduino/cores/packagemanager task test-unit
+```
+TEST_REGEX='^TestFindBoardWithFQBN$' TARGETS=./arduino/cores/packagemanager task test-unit
+```
 
 ### Integration tests
 
@@ -262,14 +268,14 @@ Before running the toolchain, perform the following operations from the root of
 virtual environment, activate it before proceeding):
 
 - go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
-- pip install -r requirements_docs.txt
+- poetry install
 
 When working on docs, you can launch a command that will take care of generating the docs, build the static website and
 start a local server you can later access with a web browser to see a preview of your changes. From the root of the git
 repository run:
 
 ```shell
-task docs:serve
+task website:serve
 ```
 
 If you don't see any error, hit http://127.0.0.1:8000 with your browser to navigate the generated docs.

docs/command-line-completion.md

@@ -29,8 +29,8 @@ a directory listed in your `fpath` if you have already created a directory to st
 Or if you want you can create a directory, add it to your `fpath` and copy the file in it:
 
 1. `mkdir ~/completion_zsh`
-2. add `fpath=($HOME/completion_zsh $fpath)` at the beginning of your `~/.zshrc` file
-3. `mv _arduino-cli ~/completion_zsh/`
+1. add `fpath=($HOME/completion_zsh $fpath)` at the beginning of your `~/.zshrc` file
+1. `mv _arduino-cli ~/completion_zsh/`
 
 Remember to open a new shell to test the functionality.
 

docs/library-specification.md

@@ -103,17 +103,19 @@ otherwise below, **all fields are required**. The available fields are:
 
 Example:
 
-    name=WebServer
-    version=1.0.0
-    author=Cristian Maglie <c.maglie@example.com>, Pippo Pluto <pippo@example.com>
-    maintainer=Cristian Maglie <c.maglie@example.com>
-    sentence=A library that makes coding a Webserver a breeze.
-    paragraph=Supports HTTP1.1 and you can do GET and POST.
-    category=Communication
-    url=http://example.com/
-    architectures=avr
-    includes=WebServer.h
-    depends=ArduinoHttpClient
+```
+name=WebServer
+version=1.0.0
+author=Cristian Maglie <c.maglie@example.com>, Pippo Pluto <pippo@example.com>
+maintainer=Cristian Maglie <c.maglie@example.com>
+sentence=A library that makes coding a Webserver a breeze.
+paragraph=Supports HTTP1.1 and you can do GET and POST.
+category=Communication
+url=http://example.com/
+architectures=avr
+includes=WebServer.h
+depends=ArduinoHttpClient
+```
 
 ### Layout of folders and files
 
@@ -130,8 +132,10 @@ numbers, underscores (\_), dots (.) and dashes (-). The maximum length is 63 cha
 For libraries intended to be used with Arduino IDE 1.5.x+ only, the source code resides in the **src** folder. For
 example:
 
-    Servo/src/Servo.h
-    Servo/src/Servo.cpp
+```
+Servo/src/Servo.h
+Servo/src/Servo.cpp
+```
 
 The source code found in **src** folder and _all its subfolders_ is compiled and linked in the user’s sketch. Only the
 _src_ folder is added to the include search path (both when compiling the sketch and the library). When the user imports
@@ -147,10 +151,12 @@ For backward compatibility with Arduino IDE 1.0.x, the library author may opt to
 instead of the folder called **src**. In this case the 1.0 library format is applied and the source code is searched
 from the **library root folder** and the **utility** folder, for example:
 
-    Servo/Servo.h
-    Servo/Servo.cpp
-    Servo/utility/ServoTimers.h
-    Servo/utility/ServoTimers.cpp
+```
+Servo/Servo.h
+Servo/Servo.cpp
+Servo/utility/ServoTimers.h
+Servo/utility/ServoTimers.cpp
+```
 
 This will allow existing 1.0 format libraries to compile under Arduino IDE 1.5.x+ as well, and vice-versa. If a library
 only needs to run on Arduino IDE 1.5.x+, we recommend placing all source code in the src/ folder. If a library requires
@@ -199,7 +205,9 @@ Servo/src/cortex-m4/fpv4-sp-d16-softfp/libServo.a
 Library examples must be placed in the **examples** folder. Note that the **examples** folder name must be written
 exactly like that (with lower case letters).
 
-    Servo/examples/...
+```
+Servo/examples/...
+```
 
 Sketches contained inside the examples folder will be shown in the Examples menu of the Arduino IDE and Arduino Web
 Editor.
@@ -223,7 +231,9 @@ inside.
 A list of keywords for the library may be specified in a file named keywords.txt located in the root of the library
 folder. When a keyword of any installed library is used in a sketch the Arduino IDE colors it.
 
-    Servo/keywords.txt
+```
+Servo/keywords.txt
+```
 
 An example keywords.txt file:
 
@@ -296,18 +306,20 @@ pick up releases that contain a .development file so be sure not to push this fi
 
 A hypothetical library named "Servo" that adheres to the specification follows:
 
-    Servo/
-    Servo/library.properties
-    Servo/keywords.txt
-    Servo/src/
-    Servo/src/Servo.h
-    Servo/src/Servo.cpp
-    Servo/src/ServoTimers.h
-    Servo/examples/
-    Servo/examples/Sweep/Sweep.ino
-    Servo/examples/Pot/Pot.ino
-    Servo/extras/
-    Servo/extras/Servo_Connectors.pdf
+```
+Servo/
+Servo/library.properties
+Servo/keywords.txt
+Servo/src/
+Servo/src/Servo.h
+Servo/src/Servo.cpp
+Servo/src/ServoTimers.h
+Servo/examples/
+Servo/examples/Sweep/Sweep.ino
+Servo/examples/Pot/Pot.ino
+Servo/extras/
+Servo/extras/Servo_Connectors.pdf
+```
 
 ## Working with multiple architectures
 
@@ -320,24 +332,28 @@ the architecture (as determined by the name of the
 
 An example:
 
-    #if defined(ARDUINO_ARCH_AVR)
-      // AVR-specific code
-    #elif defined(ARDUINO_ARCH_SAM)
-      // SAM-specific code
-    #else
-      // generic, non-platform specific code
-    #endif
+```cpp
+#if defined(ARDUINO_ARCH_AVR)
+  // AVR-specific code
+#elif defined(ARDUINO_ARCH_SAM)
+  // SAM-specific code
+#else
+  // generic, non-platform specific code
+#endif
+```
 
 Alternatively, if a library only works on certain architectures, you can provide an explicit error message (instead of
 allowing the compilation to fail in a difficult to understand way):
 
-    #if defined(ARDUINO_ARCH_AVR)
-      // AVR-specific code
-    #elif defined(ARDUINO_ARCH_SAM)
-      // SAM-specific code
-    #else
-      #error “This library only supports boards with an AVR or SAM processor.”
-    #endif
+```cpp
+#if defined(ARDUINO_ARCH_AVR)
+  // AVR-specific code
+#elif defined(ARDUINO_ARCH_SAM)
+  // SAM-specific code
+#else
+  #error “This library only supports boards with an AVR or SAM processor.”
+#endif
+```
 
 ## Old library format (pre-1.5)
 

docs/build.py → docs/siteversion/siteversion.py

@@ -1,9 +1,9 @@
-# This file is part of arduino-cli.
+# Source:
+# 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/)
 
-# This software is released under the GNU General Public License version 3,
-# which covers the main part of arduino-cli.
+# 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
 
@@ -13,48 +13,41 @@
 # Arduino software without disclosing the source code of your own applications.
 # To purchase a commercial license, send an email to license@arduino.cc.
 import os
-import sys
 import re
-import unittest
-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
+# 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 = ["master"]
-
-
-class TestScript(unittest.TestCase):
-    def test_get_docs_version(self):
-        ver, alias = get_docs_version("master", [])
-        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)
+DEV_BRANCHES = ["master"]  # Name of the branch used for the "dev" website source content
 
 
 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):
@@ -76,50 +69,27 @@ def get_rel_branch_names(blist):
     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)
-
+def main():
     # Detect repo root folder
     here = os.path.dirname(os.path.realpath(__file__))
-    repo_dir = os.path.join(here, "..")
+    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
+    # 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 tests:
-#         $python build.py test
-#
 #     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

@@ -1,6 +1,7 @@
+// Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/cobra/docsgen/go.mod
 module github.com/arduino/arduino-cli/docsgen
 
-go 1.14
+go 1.16
 
 replace github.com/arduino/arduino-cli => ../
 

docsgen/main.go

@@ -1,9 +1,8 @@
-// This file is part of arduino-cli.
+// Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/cobra/docsgen/main.go
 //
 // Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
 //
-// This software is released under the GNU General Public License version 3,
-// which covers the main part of arduino-cli.
+// 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
 //
@@ -13,10 +12,10 @@
 // Arduino software without disclosing the source code of your own applications.
 // To purchase a commercial license, send an email to license@arduino.cc.
 
+// Package main generates Markdown documentation for the project's CLI.
 package main
 
 import (
-	"log"
 	"os"
 
 	"github.com/arduino/arduino-cli/cli"
@@ -26,14 +25,17 @@ import (
 
 func main() {
 	if len(os.Args) < 2 {
-		log.Fatal("Please provide output folder")
+		print("error: Please provide the output folder argument")
+		os.Exit(1)
 	}
 
+	os.MkdirAll(os.Args[1], 0755) // Create the output folder if it doesn't already exist
+
 	configuration.Settings = configuration.Init(configuration.FindConfigFileInArgsOrWorkingDirectory(os.Args))
 	cli := cli.NewCommand()
 	cli.DisableAutoGenTag = true // Disable addition of auto-generated date stamp
 	err := doc.GenMarkdownTree(cli, os.Args[1])
 	if err != nil {
-		log.Fatal(err)
+		panic(err)
 	}
 }

mkdocs.yml

@@ -1,62 +1,48 @@
-# Project information
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/mkdocs/mkdocs.yml
+# See: https://www.mkdocs.org/user-guide/configuration/
+
 site_name: Arduino CLI
 site_description: Arduino Command Line Interface
 site_url: https://arduino.github.io/arduino-cli/
 
-# Repository
 repo_name: arduino/arduino-cli
 repo_url: https://github.com/arduino/arduino-cli
-edit_uri: ""
+edit_uri: blob/master/docs/
 
-# Copyright
 copyright: Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
 
-# Theme
 theme:
   name: material
   logo: img/icon_mac_light.png
   palette:
     primary: teal
     accent: orange
 
-# Extensions
 markdown_extensions:
-  - markdown.extensions.admonition
   - markdown.extensions.codehilite:
       guess_lang: false
-  - markdown.extensions.def_list
-  - markdown.extensions.footnotes
-  - markdown.extensions.meta
   - markdown.extensions.toc:
       permalink: true
-  - pymdownx.arithmatex
+  - mdx_truly_sane_lists:
+      nested_indent: 2
+      truly_sane: true
   - pymdownx.betterem:
       smart_enable: all
-  - pymdownx.caret
-  - pymdownx.critic
   - pymdownx.details
   - pymdownx.emoji:
-      emoji_index: !!python/name:pymdownx.emoji.twemoji
       emoji_generator: !!python/name:pymdownx.emoji.to_svg
-  - pymdownx.inlinehilite
-  - pymdownx.keys
+      emoji_index: !!python/name:pymdownx.emoji.twemoji
   - pymdownx.magiclink:
+      repo: arduino-cli
       repo_url_shorthand: true
       user: arduino
-      repo: arduino-cli
-  - pymdownx.mark
-  - pymdownx.smartsymbols
   - pymdownx.superfences
   - pymdownx.tasklist:
       custom_checkbox: true
   - pymdownx.tilde
-  - mdx_truly_sane_lists:
-      nested_indent: 2
-      truly_sane: true
 
-# Navigation
 nav:
-  - Documentation Home: index.md
+  - Home: index.md
   - installation.md
   - UPGRADING.md
   - getting-started.md
@@ -123,8 +109,6 @@ nav:
   - platform-specification.md
   - Package index specification: package_index_json-specification.md
 
-extra_css:
-  - css/version-select.css
-
-extra_javascript:
-  - js/version-select.js
+extra:
+  version:
+    provider: mike

pyproject.toml

@@ -22,6 +22,13 @@ pytest-xdist = "^2.1.0"
 pytest_httpserver = "^0.3.5"
 GitPython = "^3.1.12"
 
+[tool.poetry.dev-dependencies]
+mkdocs = "^1.2.1"
+mkdocs-material = "^7.1.8"
+mdx-truly-sane-lists = "^1.2"
+GitPython = "^3.1.20"
+mike = "^1.0.1"
+
 [tool.black]
 line-length = 120
 target-version = ["py38"]