[skip changelog] Sync documentation assets with templates (#1383)

* [skip changelog] Sync documentation assets with templates 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" assets, and those are introduced to this repository here. Notable: - Use markdownlint to check for common problems and formatting. - Make link check task Windows compatible - Streamline website versioning system - Use modern MkDocs versioning features - Make command reference generation task Windows compatible - Consolidate all Python dependency management to Poetry - Standardize documentation-related task names and deprecate old task names * Remove obsolete documentation tasks The sync with the template documentation assets has resulted in new standardized names for some of the documentation management tasks: - `docs:gen:commands` -> `go:cli-docs` - `docs:gen` -> `docs:generate` - `docs:build` -> `docs:check` - `docs:serve` -> `website:serve` - `docs:check-links` -> `markdown:check-links` * [skip changelog] Use standard list prefix in Markdown This is the standardized ordered list prefix for use in all Arduino Tooling Markdown files. The Markdown renderer will automatically handle numbering. Manual numbering means that either all following list items need to be renumbered every time a list item is added or removed, resulting in more work for contributors and reviewers. * [skip changelog] Use standardized Markdown code block style "Code fencing" is superior to the indentation code block syntax of Markdown because it permits syntax highlighting. Even in cases where syntax highlighting is not applicable, a consistent style should be used throughout all the Markdown files of Arduino Tooling projects.
arduino · Aug 10, 2021 · f04d18fffc6b0030f565384b1f4ff1b7309056db · f04d18f
1 parent a067638
commit f04d18fffc6b0030f565384b1f4ff1b7309056db
diff --git a/.github/workflows/check-markdown-task.yml b/.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
diff --git a/.github/workflows/check-mkdocs-task.yml b/.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
diff --git a/.github/workflows/deploy-cobra-mkdocs-versioned-poetry.yml b/.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 }}
diff --git a/.github/workflows/link-validation.yaml b/.github/workflows/link-validation.yaml