Skip to content

Commit 1e4038e

Browse files
committed
Format the documentation to make default input values easy to find
Previously, the information on whether an input had a default value -- and if so, what -- was incorporated into the input description. This meant you had to read the entire description to find this information. When using other actions, I have regularly had difficulty determining which inputs are required and default input values. I would like for the users of this action to not have that experience.
1 parent bc91ec5 commit 1e4038e

File tree

1 file changed

+62
-33
lines changed

1 file changed

+62
-33
lines changed

README.md

Lines changed: 62 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -11,19 +11,23 @@ This action checks whether Arduino sketches compile and produces a report of dat
1111

1212
### `cli-version`
1313

14-
The version of [Arduino CLI](https://github.com/arduino/arduino-cli) to use. Default `"latest"`.
14+
The version of [Arduino CLI](https://github.com/arduino/arduino-cli) to use.
15+
16+
**Default**: `"latest"`
1517

1618
### `fqbn`
1719

18-
The fully qualified board name to use when compiling. Default `"arduino:avr:uno"`.
20+
The fully qualified board name to use when compiling.
21+
22+
**Default**: `"arduino:avr:uno"`
1923

2024
If the board is from one of the platforms provided by Arduino's [default package index](https://downloads.arduino.cc/packages/package_index.json), the board's platform dependency will be automatically detected and the latest version installed. For boards of platforms not in the default package index, previous versions, or other platform sources, the platform dependency must be defined via the [`platforms` input](#platforms).
2125

2226
### `platforms`
2327

2428
YAML-format list of platform dependencies to install.
2529

26-
Default `""`. If no `platforms` input is provided, the board's dependency will be automatically determined from the `fqbn` input and the latest version of that platform will be installed via Boards Manager.
30+
**Default**: The board's dependency will be automatically determined from the `fqbn` input and the latest version of that platform will be installed via Boards Manager.
2731

2832
If a platform dependency from a non-Boards Manager source of the same name as another Boards Manager source platform dependency is defined, they will both be installed, with the non-Boards Manager dependency overwriting the Boards Manager platform installation. This permits testing against a non-release version of a platform while using Boards Manager to install the platform's tools dependencies.
2933
Example:
@@ -41,36 +45,42 @@ platforms: |
4145
##### Boards Manager
4246
4347
Keys:
44-
- `name` - platform name in the form of `VENDOR:ARCHITECTURE`.
45-
- `version` - version of the platform to install. Default is the latest version.
46-
- `source-url` - Boards Manager URL of the platform. Default is Arduino's package index, which allows installation of all official platforms.
48+
- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`.
49+
- `version` - version of the platform to install.
50+
- **Default**: the latest version.
51+
- `source-url` - Boards Manager URL of the platform.
52+
- **Default**: Arduino's package index, which allows installation of all official platforms.
4753

4854
##### Local path
4955

5056
Keys:
51-
- `source-path` - path to install as a platform. Relative paths are assumed to be relative to the root of the repository.
52-
- `name` - platform name in the form of `VENDOR:ARCHITECTURE`.
57+
- `source-path` - (**required**) path to install as a platform. Relative paths are assumed to be relative to the root of the repository.
58+
- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`.
5359

5460
##### Repository
5561

5662
Keys:
57-
- `source-url` - URL to clone the repository from. It must start with `git://` or end with `.git`.
58-
- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. By default, the repository will be checked out to the tip of the default branch.
59-
- `source-path` - path to install as a platform. Paths are relative to the root of the repository. The default is to install from the root of the repository.
60-
- `name` - platform name in the form of `VENDOR:ARCHITECTURE`.
63+
- `source-url` - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`.
64+
- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`.
65+
- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used.
66+
- **Default**: the repository is checked out to the tip of the default branch.
67+
- `source-path` - path to install as a platform. Paths are relative to the root of the repository.
68+
- **Default**: root of the repository.
6169

6270
##### Archive download
6371

6472
Keys:
65-
- `source-url` - download URL for the archive (e.g., `https://github.com/arduino/ArduinoCore-avr/archive/master.zip`).
66-
- `source-path` - path to install as a platform. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. The default is to install from the root folder of the archive.
67-
- `name` - platform name in the form of `VENDOR:ARCHITECTURE`.
73+
- `source-url` - (**required**) download URL for the archive (e.g., `https://github.com/arduino/ArduinoCore-avr/archive/master.zip`).
74+
- `name` - (**required**) platform name in the form of `VENDOR:ARCHITECTURE`.
75+
- `source-path` - path to install as a platform. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder.
76+
- **Default**: root folder of the archive.
6877

6978
### `libraries`
7079

7180
YAML-format list of library dependencies to install.
7281

73-
Default `"- source-path: ./"`. This causes the repository to be installed as a library. If there are no library dependencies and you want to override the default, set the `libraries` input to an empty list (`- libraries: '-'`).
82+
**Default**: `"- source-path: ./"`
83+
This causes the repository to be installed as a library. If there are no library dependencies and you want to override the default, set the `libraries` input to an empty list (`- libraries: '-'`).
7484
7585
Libraries are installed under the Arduino user folder at `~/Arduino/libraries`.
7686

@@ -81,53 +91,72 @@ Note: when the deprecated space-separated list format of this input is used, the
8191
##### Library Manager
8292

8393
Keys:
84-
- `name` - name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. The library will be installed to a folder matching the name, but with any spaces replaced by `_`.
85-
- `version` - version of the library to install. Default is the latest version.
94+
- `name` - (**required**) name of the library, as defined in the `name` field of its [library.properties](https://arduino.github.io/arduino-cli/latest/library-specification/#libraryproperties-file-format) metadata file. The library will be installed to a folder matching the name, but with any spaces replaced by `_`.
95+
- `version` - version of the library to install.
96+
- **Default**: the latest version.
8697

8798
##### Local path
8899

89100
Keys:
90-
- `source-path` - path to install as a library. Relative paths are assumed to be relative to the root of the repository.
91-
- `destination-name` - folder name to install the library to. By default, the folder will be named according to the source repository or subfolder name.
101+
- `source-path` - (**required**) path to install as a library. Relative paths are assumed to be relative to the root of the repository.
102+
- `destination-name` - folder name to install the library to.
103+
- **Default**: the folder will be named according to the source repository or subfolder name.
92104

93105
##### Repository
94106

95107
Keys:
96-
- `source-url` - URL to clone the repository from. It must start with `git://` or end with `.git`.
97-
- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used. By default, the repository will be checked out to the tip of the default branch.
98-
- `source-path` - path to install as a library. Paths are relative to the root of the repository. The default is to install from the root of the repository.
99-
- `destination-name` - folder name to install the library to. By default, the folder will be named according to the source repository or subfolder name.
108+
- `source-url` - (**required**) URL to clone the repository from. It must start with `git://` or end with `.git`.
109+
- `version` - [Git ref](https://git-scm.com/book/en/v2/Git-Internals-Git-References) of the repository to checkout. The special version name `latest` will cause the latest tag to be used.
110+
- **Default**: the tip of the default branch.
111+
- `source-path` - path to install as a library. Paths are relative to the root of the repository.
112+
- **Default**: root of the repository.
113+
- `destination-name` - folder name to install the library to.
114+
- **Default**: named according to the source repository or subfolder name.
100115

101116
##### Archive download
102117

103118
Keys:
104-
- `source-url` - download URL for the archive (e.g., `https://github.com/arduino-libraries/Servo/archive/master.zip`).
105-
- `source-path` - path to install as a library. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder. The default is to install from the root folder of the archive.
106-
- `destination-name` - folder name to install the library to. By default, the folder will be named according to the source archive or subfolder name.
119+
- `source-url` - (**required**) download URL for the archive (e.g., `https://github.com/arduino-libraries/Servo/archive/master.zip`).
120+
- `source-path` - path to install as a library. Paths are relative to the root folder of the archive, or the root of the archive if it has no root folder.
121+
- **Default**: root folder of the archive.
122+
- `destination-name` - folder name to install the library to.
123+
- **Default**: named according to the source archive or subfolder name.
107124

108125
### `sketch-paths`
109126

110-
YAML-format list of paths containing sketches to compile. These paths will be searched recursively. Default `- examples`.
127+
YAML-format list of paths containing sketches to compile. These paths will be searched recursively.
128+
129+
**Default**: `"- examples"`
111130

112131
### `verbose`
113132

114-
Set to true to show verbose output in the log. Default `false`
133+
Set to true to show verbose output in the log.
134+
135+
**Default**: `false`
115136

116137
### `sketches-report-path`
117138

118-
Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. This report is used by the `arduino/report-size-deltas` and `arduino/report-size-trends` actions. Default `"size-deltas-reports"`.
139+
Path in which to save a JSON formatted file containing data from the sketch compilations. Should be used only to store reports. Relative paths are relative to [`GITHUB_WORKSPACE`](https://help.github.com/en/actions/configuring-and-managing-workflows/using-environment-variables). The folder will be created if it doesn't already exist. This report is used by the `arduino/report-size-deltas` and `arduino/report-size-trends` actions.
140+
141+
**Default**: `"size-deltas-reports"`
119142

120143
### `github-token`
121144

122-
GitHub access token used to get information from the GitHub API. Only needed for private repositories with `enable-deltas-report` set to `true`. It will be convenient to use [`${{ secrets.GITHUB_TOKEN }}`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token). Default `""`.
145+
GitHub access token used to get information from the GitHub API. Only needed for private repositories with `enable-deltas-report` set to `true`. It will be convenient to use [`${{ secrets.GITHUB_TOKEN }}`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token).
146+
147+
**Default**: `""`
123148

124149
### `enable-deltas-report`
125150

126-
Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. If the workflow is triggered by a `pull_request` event, the comparison is between the pull request branch and the tip of the pull request's base branch. If the workflow is triggered by a `push` event, the comparison is between the pushed commit and its immediate parent. The deltas will be displayed in the GitHub Actions build log. This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas). Default `false`.
151+
Set to `true` to cause the action to determine the change in memory usage and compiler warnings of the compiled sketches. If the workflow is triggered by a `pull_request` event, the comparison is between the pull request branch and the tip of the pull request's base branch. If the workflow is triggered by a `push` event, the comparison is between the pushed commit and its immediate parent. The deltas will be displayed in the GitHub Actions build log. This may be used with the [`arduino/report-size-deltas` action](https://github.com/arduino/report-size-deltas).
152+
153+
**Default**: `false`
127154

128155
### `enable-warnings-report`
129156

130-
Set to `true` to cause the action to record the compiler warning count for each sketch compilation in the sketches report. Default `false`.
157+
Set to `true` to cause the action to record the compiler warning count for each sketch compilation in the sketches report.
158+
159+
**Default**: `false`
131160

132161
## Example usage
133162

0 commit comments

Comments
 (0)