GitLab

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.

The previous description made it sound like a convenience feature, with the build.board property only needed if you prefer a custom value for some reason. However, the resulting warning can cause confusion and act as a "red herring" for users of board definitions that don't define a build.board property.

* Document how the `packager` value of a tool reference is defined

Referencing tools from another package is any important concept for platform authors to understand. Previously, you had to guess as to what the "packager" value of a tool reference is, which was not obvious due to it being defined outside the tool's definition, and thus not mentioned at all in the "Tools definitions" section of the specification, which is the obvious place to look for this information.

The situation is made more complicated by the fact that what is called "packager" in a tool reference is referred to as "vendor" everywhere else in the documentation.

* Make it clear that tool references in package index result in installation

The platforms containing referenced cores, variants, and even tools in the case of manual platform installation, must have been installed. This could lead a platform author to think the same applies to the tools referenced from other packages by the platform's toolsDependencies field in package_index.json and that this results in their platform having a dependency on the other package's platform which uses the tool.

* [skip changelog] Add linting/formatting tasks and CI checks for docs and config files

* [skip changelog] Format all docs and config files

* [skip changelog] Update contributing documentation with formatting instructions

* [skip changelog] Fix some Prettier configuration issues

* [skip changelog] Format all config files

* [skip changelog] Fix documentation indentation issue

* [skip changelog] Removed files from .prettierignore

* [skip changelog] Update docs/package_index_json-specification.md
Co-authored-by: per1234 <accounts@perglass.com>

* [skip changelog] Format PR and issues templates

* [skip changelog] Format files after rebase

* [skip changelog] Update .prettierrc and reformat everything
Co-authored-by: per1234 <accounts@perglass.com>

* Add Description field to lib list output

* [skip changelog] Fix lib list output

Output columns are now smaller, sentence is cut if too long and renamed
Sentence column to Description.

* [skip changelog] Fixed lib list output on Windows

[skip changelog] Add link to library dependency resolution process docs from library specification (#842)

Many of the things documented in the library specification are used as determining factors in library dependency resolution. An understanding of how the components of a library influence dependency resolution priorities can be very helpful to a library developer.

Previously, only the serial.port property was documented. However, serial.port.file is in widespread use (e.g., Arduino SAMD Boards).

* Make install script's check for conflicting $PATH installation more reliable

Previously, the comparison between the install script's target path and the path of an existing installation in $PATH could easily give a false positive, producing a spurious "An existing arduino-cli was found at..." error. The solution is to fully resolve the paths before comparing them.

* Don't fail installation script when other installation in $PATH is detected

Previously, when a different installation of Arduino CLI was detected in $PATH by the installation script, the error message "Failed to install arduino-cli" would be printed and the script would have exit status 1.

It is wise that the script warns of this situation ("An existing arduino-cli was found at..."), but the "Failed to install arduino-cli" error message was misleading, since Arduino CLI was indeed installed. It is also incorrect to have an error exit status in this situation, since the user may intend to have multiple installations and provide the full path when using the new installation.