From 0a327002ac74765b45dc699fffceaf67a107c23e Mon Sep 17 00:00:00 2001 From: Silvano Cerza Date: Tue, 28 Jul 2020 16:13:46 +0200 Subject: [PATCH 1/3] [skip changelog] Add task and workflow to check for dead links in docs --- .github/workflows/link-validation.yaml | 25 +++++++++++++++++++++++++ Taskfile.yml | 6 ++++++ 2 files changed, 31 insertions(+) create mode 100644 .github/workflows/link-validation.yaml diff --git a/.github/workflows/link-validation.yaml b/.github/workflows/link-validation.yaml new file mode 100644 index 00000000000..cb9267a614a --- /dev/null +++ b/.github/workflows/link-validation.yaml @@ -0,0 +1,25 @@ +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: Verify links + run: task docs:check-links diff --git a/Taskfile.yml b/Taskfile.yml index 35564237461..0e875544201 100755 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -54,6 +54,12 @@ tasks: cmds: - npx {{ .PRETTIER }} --check "**/*.md" + docs:check-links: + desc: Verifies there are no dead links in documentation + dir: docs + cmds: + - npx -p markdown-link-check -c 'for file in **/*.md; do markdown-link-check -q "$file"; done' + docs:format: desc: Automatically formats documentation cmds: From b42c39423b4c7d46e1f3f3bc8553f88cee185912 Mon Sep 17 00:00:00 2001 From: Silvano Cerza Date: Wed, 29 Jul 2020 09:59:48 +0200 Subject: [PATCH 2/3] [skip changelog] Fix link checking task and workflow --- .github/workflows/link-validation.yaml | 36 ++++++++++++++++++++++++++ Taskfile.yml | 10 +++++-- markdown-link-check-config.json | 10 +++++++ 3 files changed, 54 insertions(+), 2 deletions(-) create mode 100644 markdown-link-check-config.json diff --git a/.github/workflows/link-validation.yaml b/.github/workflows/link-validation.yaml index cb9267a614a..484071b4cc2 100644 --- a/.github/workflows/link-validation.yaml +++ b/.github/workflows/link-validation.yaml @@ -21,5 +21,41 @@ jobs: 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 diff --git a/Taskfile.yml b/Taskfile.yml index 0e875544201..ac597457a89 100755 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -56,9 +56,15 @@ tasks: docs:check-links: desc: Verifies there are no dead links in documentation - dir: docs cmds: - - npx -p markdown-link-check -c 'for file in **/*.md; do markdown-link-check -q "$file"; done' + - | + 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 diff --git a/markdown-link-check-config.json b/markdown-link-check-config.json new file mode 100644 index 00000000000..0ec33e8541f --- /dev/null +++ b/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*" + } + ] +} From 0f3738ee085310e22dfccf1d91d03866f2e266c5 Mon Sep 17 00:00:00 2001 From: Silvano Cerza Date: Wed, 29 Jul 2020 11:11:46 +0200 Subject: [PATCH 3/3] [skip changelog] Fix some documentation links --- docs/CONTRIBUTING.md | 5 ++--- docs/configuration.md | 8 ++++---- docs/index.md | 2 +- docs/integration-options.md | 4 ++-- docs/library-specification.md | 6 +++--- docs/platform-specification.md | 6 +++--- docs/sketch-build-process.md | 2 +- docs/sketch-specification.md | 4 ++-- 8 files changed, 18 insertions(+), 19 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index db098fca904..993f06a1453 100644 --- a/docs/CONTRIBUTING.md +++ b/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 diff --git a/docs/configuration.md b/docs/configuration.md index aea470b5677..5e040e25dba 100644 --- a/docs/configuration.md +++ b/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 diff --git a/docs/index.md b/docs/index.md index d40820b0114..6d6f89954dd 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/integration-options.md b/docs/integration-options.md index 2675b59e38b..47be96ac40c 100644 --- a/docs/integration-options.md +++ b/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 diff --git a/docs/library-specification.md b/docs/library-specification.md index 5331f64201a..269bba55475 100644 --- a/docs/library-specification.md +++ b/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:
`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 diff --git a/docs/platform-specification.md b/docs/platform-specification.md index c80cfccac07..2e283e0b2a0 100644 --- a/docs/platform-specification.md +++ b/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.
The **version** is currently +[`arduino-cli core list`](commands/arduino-cli_core_list.md)'s output for the platform.
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 diff --git a/docs/sketch-build-process.md b/docs/sketch-build-process.md index 5186d4ccb9e..9d59f64f36a 100644 --- a/docs/sketch-build-process.md +++ b/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 diff --git a/docs/sketch-specification.md b/docs/sketch-specification.md index a126a89c9ed..d5a2f05dd54 100644 --- a/docs/sketch-specification.md +++ b/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