Merge pull request #225 from per1234/website

Sync website assets from templates

Author: per1234

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

@@ -0,0 +1,63 @@
+# 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.14"
+  # 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/**"
+      - "docsgen/**"
+      - "**.go"
+  pull_request:
+    paths:
+      - ".github/workflows/check-mkdocs-task.ya?ml"
+      - "Taskfile.ya?ml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
+      - "docs/**"
+      - "docsgen/**"
+      - "**.go"
+  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 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/check-python-task.yml

@@ -2,7 +2,7 @@ name: Check Python
 
 env:
   # See: https://github.com/actions/setup-python/tree/v2#available-versions-of-python
-  PYTHON_VERSION: "3.8"
+  PYTHON_VERSION: "3.9"
 
 # See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows
 on:

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

@@ -1,16 +1,24 @@
-name: Publish documentation
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/deploy-cobra-mkdocs-versioned-poetry.md
+name: Deploy Website
 
 on:
   push:
     branches:
+      # Branch to base "dev" website on. Set in siteversion.py also.
       - main
       # 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/**"
-      - "cli/**"
-      - ".github/workflows/publish-docs.yml"
+      - "mkdocs.ya?ml"
+      - "poetry.lock"
+      - "pyproject.toml"
   # Run on branch or tag creation (will be filtered by the publish-determination job).
   create:
 
@@ -38,46 +46,45 @@ jobs:
     if: needs.publish-determination.outputs.result == 'true'
 
     steps:
-      - name: Checkout local repository
+      - 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 Go
-        uses: actions/setup-go@v2
-        with:
-          go-version: "1.14"
-
       - name: Install Python
         uses: actions/setup-python@v2
         with:
-          python-version: "3.8"
-
-      - name: Cache dependencies
-        uses: actions/cache@v2
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('./pyproject.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
+          python-version: "3.9"
 
       - 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
-        # 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.
+        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 "bot@arduino.cc"
           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
+          poetry run mike deploy \
+            --update-aliases \
+            --push \
+            --remote origin \
+            ${{ fromJson(steps.determine-versioning.outputs.data).version }} \
+            ${{ fromJson(steps.determine-versioning.outputs.data).alias }}

.github/workflows/spell-check.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Install Python
         uses: actions/setup-python@v2
         with:
-          python-version: "3.8"
+          python-version: "3.9"
 
       - name: Install Poetry
         run: pip install poetry

.github/workflows/test.yml

@@ -75,7 +75,7 @@ jobs:
       - name: Install Python
         uses: actions/setup-python@v2
         with:
-          python-version: "3.8"
+          python-version: "3.9"
 
       - name: Install Poetry
         run: pip install poetry

.github/workflows/validate-docs.yml

@@ -5,7 +5,8 @@
 [![Publish Nightly Build status](https://github.com/arduino/arduino-lint/actions/workflows/publish-go-nightly-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/publish-go-nightly-task.yml)
 [![Check Python status](https://github.com/arduino/arduino-lint/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-python-task.yml)
 [![Check Markdown status](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-markdown-task.yml)
-[![Docs Status](https://github.com/arduino/arduino-lint/workflows/Publish%20documentation/badge.svg)](https://github.com/arduino/arduino-lint/actions?workflow=Publish+documentation)
+[![Check Website status](https://github.com/arduino/arduino-lint/actions/workflows/check-mkdocs-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-mkdocs-task.yml)
+[![Deploy Website status](https://github.com/arduino/arduino-lint/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml)
 [![Codecov](https://codecov.io/gh/arduino/arduino-lint/branch/main/graph/badge.svg?token=nprqPQMbdh)](https://codecov.io/gh/arduino/arduino-lint)
 [![Check Prettier Formatting status](https://github.com/arduino/arduino-lint/actions/workflows/check-prettier-formatting-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-prettier-formatting-task.yml)
 [![Check General Formatting status](https://github.com/arduino/arduino-lint/actions/workflows/check-general-formatting-task.yml/badge.svg)](https://github.com/arduino/arduino-lint/actions/workflows/check-general-formatting-task.yml)

README.md

@@ -226,40 +226,40 @@ tasks:
     cmds:
       - poetry run black .
 
+  # 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
+      - task: go:cli-docs
+      # Make the formatting consistent with the non-generated Markdown
+      - task: general:format-prettier
 
-  docs:gen:
-    desc: Generate command reference
+  # 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:
-      # docs will generate examples using os.Args[0] so we need to call
-      # the generator `arduino-lint`
-      - go build -o arduino-lint{{exeExt}}
-      # we invoke `arduino-lint` like this instead of `./arduino-lint` to remove
-      # the `./` chars from the examples
-      - PATH=. arduino-lint ../docs/commands
-      - task: general:format-prettier
+      # 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:build:
-    desc: Build documentation website contents
+  # 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:
-      - task: docs:gen
-      - poetry install --no-root
       - poetry run mkdocs build --strict
 
-  docs:publish:
-    desc: Use Mike to build and push versioned docs
-    cmds:
-      - task: docs:gen
-      - poetry run mike deploy --update-aliases --push --remote {{.DOCS_REMOTE}} {{.DOCS_VERSION}} {{.DOCS_ALIAS}}
-
-  docs:serve:
-    desc: Run documentation website locally
+  # 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:
-      - task: docs:build
       - poetry run mkdocs serve
 
   docs:check:

Taskfile.yml

@@ -81,7 +81,7 @@ To build Arduino Lint from sources you need the following tools to be available
 
 If you want to run integration tests or work on documentation, you will also need:
 
-- A working [Python](https://www.python.org/downloads/) environment, version 3.8 or later.
+- A working [Python](https://www.python.org/downloads/) environment, version 3.9 or later.
 - [Poetry](https://python-poetry.org/docs/).
 
 ### Building the source code
@@ -232,7 +232,7 @@ documentation website. You can build the documentation website and serve it from
 command:
 
 ```
-task docs:serve
+task website:serve
 ```
 
 The documentation will build. If you don't see any error, open `http://127.0.0.1:8000` in your browser to local the
@@ -254,7 +254,7 @@ Otherwise you can use the following tasks. To do so you'll need to install `npm`
 To check if the files are correctly formatted run:
 
 ```shell
-task docs:check
+task website:check
 ```
 
 If the output tells you that some files are not formatted correctly run: