[skip changelog] Add task and workflow to check for dead links in docs (#878)

* [skip changelog] Add task and workflow to check for dead links in docs

* [skip changelog] Fix link checking task and workflow

* [skip changelog] Fix some documentation links

Author: silvanocerza

.github/workflows/link-validation.yaml

@@ -0,0 +1,61 @@
+name: Verifies documentation links
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  schedule:
+    - cron: "0 3 * * 1" # Every Monday at 03:00
+
+jobs:
+  verify-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 1
+
+      - name: Install Taskfile
+        uses: Arduino/actions/setup-taskfile@master
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install Go
+        uses: actions/setup-go@v2
+        with:
+          go-version: "1.14"
+
+      - name: Installs Go dependencies
+        shell: bash
+        run: go get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc
+
+      - name: Install protoc compiler
+        uses: arduino/setup-protoc@v1.1.0
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: "3.6"
+          architecture: "x64"
+
+      - name: Cache dependencies
+        uses: actions/cache@v1
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -r ./requirements_docs.txt
+
+      - name: Build docs
+        run: task docs:build
+
+      - name: Verify links
+        run: task docs:check-links

Taskfile.yml

@@ -54,6 +54,18 @@ tasks:
     cmds:
       - npx {{ .PRETTIER }} --check "**/*.md"
 
+  docs:check-links:
+    desc: Verifies there are no dead links in documentation
+    cmds:
+      - |
+        npx -p markdown-link-check -c '
+        STATUS=0
+        for file in $(find -name "*.md"); do
+          markdown-link-check -c markdown-link-check-config.json -q "$file"
+          STATUS=$(( $STATUS + $? ))
+        done
+        exit $STATUS'
+
   docs:format:
     desc: Automatically formats documentation
     cmds:

docs/CONTRIBUTING.md

@@ -218,8 +218,8 @@ If you don't see any error, hit http://127.0.0.1:8000 with your browser to navig
 ### Docs publishing
 
 The present git repository has a special branch called `gh-pages` that contains the generated HTML code for the docs
-website; every time a change is pushed to this special branch, GitHub automatically triggers a [deployment][8] to pull
-the change and publish a new version of the website. Do not open Pull Requests to push changes to the `gh-pages` branch,
+website; every time a change is pushed to this special branch, GitHub automatically triggers a deployment to pull the
+change and publish a new version of the website. Do not open Pull Requests to push changes to the `gh-pages` branch,
 that will be done exclusively from the CI.
 
 ### Docs versioning
@@ -342,7 +342,6 @@ If your PR doesn't need to be included in the changelog, please start the PR tit
 [5]: https://github.com/ofek/hatch
 [6]: https://github.com/protocolbuffers/protobuf/releases
 [7]: https://pages.github.com/
-[8]: https://github.com/arduino/arduino-cli/deployments?environment=github-pages#activity-log
 [9]: https://www.mkdocs.org/
 [10]: https://github.com/jimporter/mike
 [11]: https://github.com/arduino/arduino-cli/blob/master/.github/workflows/docs.yaml

docs/configuration.md

@@ -126,12 +126,12 @@ additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index
 
 [grpc]: https://grpc.io
 [sketchbook directory]: sketch-specification.md#sketchbook
-[arduino-cli config dump]: ../commands/arduino-cli_config_dump
-[arduino cli command reference]: ../commands/arduino-cli
-[arduino-cli global flags]: ../commands/arduino-cli_config/#options-inherited-from-parent-commands
+[arduino-cli config dump]: commands/arduino-cli_config_dump.md
+[arduino cli command reference]: commands/arduino-cli.md
+[arduino-cli global flags]: commands/arduino-cli_config.md#options-inherited-from-parent-commands
 [export command]: https://ss64.com/bash/export.html
 [set command]: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1
-[arduino-cli config init]: ../commands/arduino-cli_config_init
+[arduino-cli config init]: commands/arduino-cli_config_init.md
 [json]: https://www.json.org
 [toml]: https://github.com/toml-lang/toml
 [yaml]: https://en.wikipedia.org/wiki/YAML

docs/index.md

@@ -17,4 +17,4 @@ services and messages are detailed in the [gRPC reference] pages.
 [installation]: installation.md
 [getting started guide]: getting-started.md
 [client_example]: https://github.com/arduino/arduino-cli/blob/master/client_example
-[grpc reference]: rpc/commands
+[grpc reference]: rpc/commands.md

docs/integration-options.md

@@ -95,10 +95,10 @@ tracker] if you’ve got a use case that doesn’t fit one of the three pillars.
 [configuration documentation]: configuration.md
 [json]: https://www.json.org
 [installation script]: installation.md#use-the-install-script
-[command reference]: ../commands/arduino-cli
+[command reference]: commands/arduino-cli.md
 [grpc]: https://grpc.io/
 [rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call
-[daemon mode]: ../commands/arduino-cli_daemon
+[daemon mode]: commands/arduino-cli_daemon.md
 [grpc interface reference]: ../rpc/commands
 [grpc supported languages]: https://grpc.io/docs/languages/
 [arduino cli repository]: https://github.com/arduino/arduino-cli

docs/library-specification.md

@@ -9,7 +9,7 @@ This new library format is intended to be used in tandem with **Library Manager*
 The Library Manager allows users to automatically download and install libraries needed in their projects, with an easy
 to use graphic interface in the [Arduino IDE](https://www.arduino.cc/en/guide/libraries#toc3)/Pro IDE and
 [Arduino Web Editor](https://create.arduino.cc/projecthub/Arduino_Genuino/getting-started-with-arduino-web-editor-on-various-platforms-4b3e4a#toc-libraries-and-the-arduino-web-editor-11)
-as well as [`arduino-cli lib`](../commands/arduino-cli_lib).
+as well as [`arduino-cli lib`](commands/arduino-cli_lib.md).
 
 More information about how Library Manager works is available
 [here](https://github.com/arduino/Arduino/wiki/Library-Manager-FAQ).
@@ -22,7 +22,7 @@ code to specific architectures.
 ## See also
 
 - [Arduino library style guide](http://arduino.cc/en/Reference/APIStyleGuide)
-- [Library dependency resolution process documentation](../sketch-build-process/#dependency-resolution)
+- [Library dependency resolution process documentation](sketch-build-process.md#dependency-resolution)
 
 ## 1.5 library format (rev. 2.2)
 
@@ -70,7 +70,7 @@ otherwise below, **all fields are required**. The available fields are:
 - **depends** - **(available from Arduino IDE 1.8.10/Arduino CLI 0.7.0)** (optional) a comma-separated list of
   dependencies (libraries that are needed to build the current library). The Arduino IDE's Library Manager will offer to
   install the dependencies during installation of the library.
-  [`arduino-cli lib install`](../commands/arduino-cli_lib_install) will automatically install the dependencies. Since
+  [`arduino-cli lib install`](commands/arduino-cli_lib_install.md) will automatically install the dependencies. Since
   spaces are allowed in the `name` of a library, but not commas, you can refer to libraries containing spaces in the
   name without ambiguity for example:<br> `depends=Very long library name, Another library with long-name`
 - **dot_a_linkage** - **(available from Arduino IDE 1.6.0 / arduino-builder 1.0.0-beta13)** (optional) when set to

docs/platform-specification.md

@@ -116,7 +116,7 @@ The following meta-data must be defined:
     version=1.5.3
 
 The **name** will be shown as the Arduino IDE's Board menu section title or the Name field of
-[`arduino-cli core list`](../commands/arduino-cli_core_list)'s output for the platform.<br> The **version** is currently
+[`arduino-cli core list`](commands/arduino-cli_core_list.md)'s output for the platform.<br> The **version** is currently
 unused, it is reserved for future use (probably together with the Boards Manager to handle dependencies on cores).
 
 ### Build process
@@ -592,7 +592,7 @@ If the user didn't enable verbose mode, then **{upload.params.quiet}** is used i
 ### Sketch upload configuration
 
 The Upload action is triggered when the user clicks on the "Upload" button on the IDE toolbar or uses
-[`arduino-cli upload`](../commands/arduino-cli_upload). Arduino uses the term "upload" for the process of transferring a
+[`arduino-cli upload`](commands/arduino-cli_upload.md). Arduino uses the term "upload" for the process of transferring a
 program to the Arduino board. The **upload.tool** property determines the tool to be used for upload. A specific
 **upload.tool** property should be defined for every board in boards.txt:
 
@@ -685,7 +685,7 @@ support uploading via programmer.
 ### Serial port
 
 The full path (e.g., `/dev/ttyACM0`) of the port selected via the IDE or
-[`arduino-cli upload`](../commands/arduino-cli_upload)'s `--port` option is available as a configuration property
+[`arduino-cli upload`](commands/arduino-cli_upload.md)'s `--port` option is available as a configuration property
 **{serial.port}**.
 
 The file component of the port's path (e.g., `ttyACM0`) is available as the configuration property

docs/sketch-build-process.md

@@ -103,7 +103,7 @@ The "folder name priority" is determined as follows (in order of highest to lowe
 The "location priority" is determined as follows (in order of highest to lowest priority):
 
 1. The library is in a custom libraries path specified via the
-   [`--libraries` option](../commands/arduino-cli_compile/#options) of `arduino-cli compile` (in decreasing order of
+   [`--libraries` option](commands/arduino-cli_compile.md#options) of `arduino-cli compile` (in decreasing order of
    priority when multiple custom paths are defined)
 1. The library is in the `libraries` subfolder of the IDE's sketchbook or Arduino CLI's user directory
 1. The library is bundled with the board platform/core

docs/sketch-specification.md

@@ -66,9 +66,9 @@ Arduino CLI and Arduino Web Editor use a file named sketch.json, located in the
 metadata.
 
 The `cpu` key contains the board configuration information. This can be set via
-[`arduino-cli board attach`](../commands/arduino-cli_board_attach/) or by selecting a board in the Arduino Web Editor
+[`arduino-cli board attach`](commands/arduino-cli_board_attach.md) or by selecting a board in the Arduino Web Editor
 while the sketch is open. With this configuration set, it is not necessary to specify the `--fqbn` or `--port` flags to
-the [`arduino-cli compile`](../commands/arduino-cli_compile/) or [`arduino-cli upload`](../commands/arduino-cli_upload/)
+the [`arduino-cli compile`](commands/arduino-cli_compile.md) or [`arduino-cli upload`](commands/arduino-cli_upload.md)
 commands when compiling or uploading the sketch.
 
 The `included_libs` key defines the library versions the Arduino Web Editor uses when the sketch is compiled. This is

markdown-link-check-config.json

@@ -0,0 +1,10 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "https?://localhost:\\d*/"
+    },
+    {
+      "pattern": "https?://(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?):\\d*"
+    }
+  ]
+}