Add infrastructure for managing table of contents

The project readme contains a table of contents in order to facilitate the navigation of the documentation.

It is important that this table of contents is kept in sync with the documentation content.

A task is added for automatically generating the ToC from the content of the file.

A GitHub Actions workflow is added to check the table of contents. On every push or pull request that affects relevant
files, it will check whether the table of contents matches the file structure.

Author: per1234

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

@@ -0,0 +1,93 @@
+# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/check-toc-task.md
+name: Check ToC
+
+env:
+  # See: https://github.com/actions/setup-node/#readme
+  NODE_VERSION: 16.x
+
+# See: https://docs.github.com/actions/using-workflows/events-that-trigger-workflows
+on:
+  create:
+  push:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      - "package.json"
+      - "package-lock.json"
+      - "README.md"
+  pull_request:
+    paths:
+      - ".github/workflows/check-toc-task.ya?ml"
+      - "package.json"
+      - "package-lock.json"
+      - "README.md"
+  schedule:
+    # Run periodically to catch breakage caused by external changes.
+    - cron: "0 3 * * WED"
+  workflow_dispatch:
+  repository_dispatch:
+
+jobs:
+  run-determination:
+    runs-on: ubuntu-latest
+    permissions: {}
+    outputs:
+      result: ${{ steps.determination.outputs.result }}
+    steps:
+      - name: Determine if the rest of the workflow should run
+        id: determination
+        run: |
+          RELEASE_BRANCH_REGEX="^refs/heads/v[0-9]+$"
+          # The `create` event trigger doesn't support `branches` filters, so it's necessary to use Bash instead.
+          if [[
+            "${{ github.event_name }}" != "create" ||
+            "${{ github.ref }}" =~ $RELEASE_BRANCH_REGEX
+          ]]; then
+            # Run the other jobs.
+            RESULT="true"
+          else
+            # There is no need to run the other jobs.
+            RESULT="false"
+          fi
+
+          echo "result=$RESULT" >> $GITHUB_OUTPUT
+
+  check:
+    name: ${{ matrix.file.name }}
+    needs: run-determination
+    if: needs.run-determination.outputs.result == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+
+      matrix:
+        file:
+          - name: README.md
+            # Max ToC depth, for use with the markdown-toc --maxdepth flag.
+            maxdepth: 4
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Install Task
+        uses: arduino/setup-task@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          version: 3.x
+
+      - name: Rebuild ToC
+        run: |
+          task markdown:toc \
+            FILE_PATH="${{ github.workspace }}/${{ matrix.file.name }}" \
+            MAX_DEPTH=${{ matrix.file.maxdepth }}
+
+      - name: Check ToC
+        run: git diff --color --exit-code

README.md

@@ -5,6 +5,7 @@
 [![Check Poetry status](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-poetry-task.yml)
 [![Check Python status](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-python-task.yml)
 [![Check Taskfiles status](https://github.com/arduino/report-size-deltas/actions/workflows/check-taskfiles.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-taskfiles.yml)
+[![Check ToC status](https://github.com/arduino/report-size-deltas/actions/workflows/check-toc-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/check-toc-task.yml)
 [![Integration Tests](https://github.com/arduino/report-size-deltas/actions/workflows/test-integration.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/test-integration.yml)
 [![Spell Check status](https://github.com/arduino/report-size-deltas/actions/workflows/spell-check-task.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/spell-check-task.yml)
 [![Sync Labels status](https://github.com/arduino/report-size-deltas/actions/workflows/sync-labels-npm.yml/badge.svg)](https://github.com/arduino/report-size-deltas/actions/workflows/sync-labels-npm.yml)

Taskfile.yml

@@ -24,6 +24,7 @@ tasks:
     deps:
       - task: general:correct-spelling
       - task: markdown:fix
+      - task: markdown:toc
       - task: poetry:sync
       - task: python:format
 
@@ -101,6 +102,19 @@ tasks:
     cmds:
       - npx markdownlint-cli "**/*.md"
 
+  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-toc-task/Taskfile.yml
+  markdown:toc:
+    desc: Update the table of contents
+    deps:
+      - task: npm:install-deps
+    cmds:
+      - |
+        npx markdown-toc \
+            --bullets=- \
+            --maxdepth={{.MAX_DEPTH}} \
+            -i \
+            "{{.FILE_PATH}}"
+
   # Parameter variables:
   # - PROJECT_PATH: path of the npm-managed project. Default value: "./"
   # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml