GitLab

* update cobra to get new zsh completion https://github.com/spf13/cobra/commit/2c5a0d300f8ba1cd142776508519aba999b5e77f and to fix this https://github.com/spf13/cobra/commit/675ae5f5a98cc705a6d54f4c487ab81230604137

* add --no-descriptions also for zsh

* update docs

* update tests

* removed hack https://github.com/spf13/cobra/issues/1121

* [skip changelog] Build is now uploaded as artifact when running tests workflow

* [skip changelog] Added more information to workflow artifacts

* [skip changelog] Fix artifacts paths

* [skip changelog] Update upload-artifact action version in test workflow

* [skip changelog] Test artifacts are now uploaded separately

* Disable workflows that would always fail from running in forks

These workflows use resources that are only available when run in the arduino/arduino-cli repository, so would always fail when they run in a repository. They are of no value to fork repositories. They are triggered by the schedule event, so they cause regular annoying and confusing workflow failure notifications for every fork owner.

* Don't trigger link validation CI workflow on schedule event when in a fork

The docs workflow was split into two workflows: publish-docs and validate-docs, but the references to the original workflow were not updated.

* Split docs workflow into validate and publish workflows

The docs workflow had two uses:

- Check that changes to docs don't break the static website build system
- Publish the docs to the website

To make the CI system friendly to contributors, it should be easy for them to validate documentation changes from a feature branch, meaning the validation aspect should run on a push to any branch. However, the special behavior of the workflow to publish on pushes conflicted with that usage. The most simple solution is to split the workflow into two. The validation workflow contains the process of interest to contributors, and is thus made friendly to their development process. The publishing workflow is not of interest to contributors, and thus doesn't need to be configured to run on pushes to any branch.

* Run workflows that are useful to contributors on push to any branch

Contributors should run CI in their feature branch to make sure it's passing before submitting a PR. Previously, the CI workflows were configured to run only on push to the master branch, meaning that contributors would need to modify the workflows just to get them to run on a feature branch. It's very unlikely that a contributor would do that, so they are more likely to just submit the PR, then if CI on the PR fails push fixup commits until CI is passing.

The solution is simply to remove the filters that caused the workflows to run only on push to master.

The v1.1.0 version of the action neglected to define its repo-token input in the metadata, which results in a `Unexpected input(s) 'repo-token', valid inputs are ['version']` warning shown in the workflow summary on every run. The v1.1.1 release remedies this.

The use of the v1 ref will allow the workflows to benefit from any new releases of the action that don't cause breaking changes.

* Use v1 ref of codecov/codecov-action GitHub Actions action

Previously, the workflow pinned the outdated v1.0.2 ref. The requirement for an upload token has been removed since the 1.0.2 release. Removing the token input will provide several benefits:

- Prevent failures when the workflow is run in forks, which won't have the CODECOV_TOKEN secret defined.
- Allow configuring the workflow to be triggered by pull_request events, making it easy to evaluate the impact the pull request has on code coverage.

The use of the v1 ref, rather than pinning a specific version allows the workflow to automatically benefit from ongoing development work on the action, while still preventing it from being affected by breaking changes.

* Remove unnecessary token input from Codecov upload steps of test workflow

With the modern versions of the codecov/codecov-action GitHub Actions action, the upload token is only required for private repositories. Now that we are using a modern version of the action, this input only has a harmful effect by causing the workflow to fail when run in forks and also preventing us from using Codecov to evaluate the impact on code coverage of pull requests.

* Add FAQ item re: Serial Monitor

* Mention gRPC Monitor service in Serial Monitor FAQ

We now use Prettier to enforce a formatting standard on the Arduino CLI documentation. Previously, the generated documentation was not compliant with this standard, which caused some problems:

Incorrect list formatting of gRPC reference's table of contents. Prettier uses a two space indent. Because the stock Python-Markdown renderer requires a four space indent for nested lists, it was necessary to start using the mdx_truly_sane_lists extension to support the Prettier indent size. The use of the extension caused the four space indent used in the generated gRPC interface documentation's nested lists to no longer be rendered. It's possible that inconsistent formatting could cause similar issues. By making the formatting of all the documentation consistent, we can be sure that a specific renderer will handle all the docs correctly.

task docs:check fails when run on repository that contains generated docs. Although this could also have been fixed by excluding the generated documentation paths, the list formatting issue needed to be fixed anyway, and it happens to fix this issue as well.

* [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

This prevents spurious test breakage caused by platform releases. These tests are about the behavior of Arduino CLI itself, not about testing the platform, so the platform should be static. There are certain tests which make sense to do with the latest release of the platforms, and those have been left as is.

The platform referencing documentation content falls into four categories:

- general
- core
- variant
- tool

Previously, it was not obvious where the content for each category began and ended.

[skip changelog] Add previously undocumented global predefined properties to platform specification (#870)

* Document extra.time.* properties

These properties provide time data from the machine running the build process.

* Add previously undocumented build.* properties to platform specification

These are built-in properties of the builder, yet were previously undocumented.

* Add miscellaneous undocumented built-in properties to platform specification

* Add outdated command to list cores and libs that needs upgrade

* Add update command to update the index of cores and libs

* Add upgrade command to upgrade all installed cores and libs

* [skip changelog] Update docs with new commands

* [skip changelog] Fix outdated and upgrade command

* [skip changelog] Changed update and outdated commands behaviour

* Revert "Add macro -DARDUINO_LIB_DISCOVERY_PHASE during lib discovery phase (#633)"

This reverts commit 985b2c99.

* Set {build.library_discovery_phase} to 1 during lib discovery

Previously we used to add `-DARDUINO_LIB_DISCOVERY_PHASE` to the gcc
command line but this produced some incompatiblity with compilers using
non-standard `-d` flag instead of `-D`:

https://github.com/arduino/arduino-cli/pull/633#issuecomment-659529026

* Move precompiled library file location documentation to dedicated section of library specification

As more documentation is added about precompiled libraries, it becomes increasingly awkward to fit in in the bullet list format of the library.properties fields section of the library specification. The specification has a dedicated "Layout of folders and files" section, which is an appropriate place to move the documentation of the precompiled binary files used with this feature. This allows the documentation of the `precompiled` library.properties field to be only about the use of that field, with a link to the section which contains the documentation about the files.

* Document floating point ABI configuration folders for precompiled libraries

These properties were previously undocumented.

Previously, the precompiled field of library.properties only supported one value: "true". As it became apparent that there were two distinct use cases for this feature, it was necessary to add a new option so that both use cases could be fully supported.

ArduinoCore-API is an important resource for core authors, so it is beneficial to alert the readers of this section of the Arduino platform specification to its existence.

By default, Cobra automatically adds a date stamp to the generated command line reference content. Having a date stamp is not necessarily a bad thing, though it's also doubtful that it is useful enough to justify its presence. However, the formatting of this date stamp causes it to be shown as an item in the table of contents of each command reference page, inappropriately located under the "SEE ALSO" heading. This clutters up the documentation without providing any benefits at all.

Fortunately, Cobra has provided an option to disable this behavior: https://github.com/spf13/cobra/blob/master/doc/README.md#disableautogentag

The pymdownx.magiclink Python-Markdown extension adds support for GitHub-style auto-linked issue/PR/commit/user references. In order for the issue/PR/commit references to work correctly in the case where no repository is specified, the extension must be configured with the owner and repository name of the repository that is using it. As a result of not having been updated after it was copied, the extension was previously configured for the squidfunk/mkdocs-material repository, which would result in any references that didn't specify a repository to be relative to that repository, rather than arduino/arduino-cli.