Improve documentation of data format of dependency inputs

[faultfactory]

Describe the problem

Supplying the board source-url for the BM .json file via the platform scheme documented does not work.

I searched through the python file to get it working and appended the URL to the fqbn field in my action file and it worked.

Please update the docs, or make the code match the docs.

To reproduce

Attempt to use a 3rd party board given the instructions in the action documentation.

This failed and gave an error indicating the information was parsed incorrectly.

      - name: Compile Arduino Sketches
        uses: arduino/compile-sketches@v1
        with:
          fqbn: 'adafruit:samd:adafruit_feather_m4_can'
          platforms:  |
            - name: "adafruit:samd"
            - source-url: "https://adafruit.github.io/arduino-board-index/package_adafruit_index.json"
          libraries: |
            - name: CAN Adafruit Fork
            - name: SafeString

This worked:

- name: Compile Arduino Sketches
        uses: arduino/compile-sketches@v1
        with:
          fqbn: 'adafruit:samd:adafruit_feather_m4_can https://adafruit.github.io/arduino-board-index/package_adafruit_index.json'
          libraries: |
            - name: CAN Adafruit Fork
            - name: SafeString

Expected behavior

Explained above.

'arduino/compile-sketches' version

v1.0.1

Additional context

No response

Issue checklist

• I searched for previous reports in the issue tracker
• I verified the problem still occurs when using the latest version
• My report contains all necessary details

[per1234]

Hi @faultfactory. Thanks for your report. Each of the elements of the platforms input list is a separate platform definition object. These objects consist of the keys mentioned in the documentation.

Your code here:

platforms:  |
  - name: "adafruit:samd"
  - source-url: "https://adafruit.github.io/arduino-board-index/package_adafruit_index.json"

contains two separate platform definition objects, one for each of the elements of the list. So you have specified that a platform with the ID adafruit:samd should be installed, then you have specified that different platform with Boards Manager package index https://adafruit.github.io/arduino-board-index/package_adafruit_index.json should be installed.

But what you were intended to do was specify a single platform. To do that, all keys must be in the same element, like this:

platforms:  |
  - name: "adafruit:samd"
    source-url: "https://adafruit.github.io/arduino-board-index/package_adafruit_index.json"

So the documentation is correct, and the action works just as documented. However, I think this indicates it is not as clear as it should be. We can use this issue to track the need to improve on that.

Probably the most helpful thing would be to provide a dedicated example snippet for each of the source type sections under the platforms input documentation (currently there is only at the top level section of that documentation).

I think the wording could also be improved to be more clear.

If anyone wants to submit pull requests proposing improvements to the documentation, I would be happy to review them.

appended the URL to the fqbn field

The code that allows that was added to provided backwards compatibility for workflows using the poorly designed API of the earliest alpha version of the action. It is deprecated and might be removed at any time. Use of that API is strongly discouraged.