Add documentation for additional-paths feature

Author: giulcioffi

docs/configuration.md

@@ -2,7 +2,8 @@
 
 - `board_manager`
   - `additional_urls` - the URLs to any additional Boards Manager package index files needed for your boards platforms.
-  - `additional_paths` - the file paths to any additional Boards Manager package index files needed for your boards platforms.
+  - `additional_paths` - the absolute file paths to any additional Boards Manager package index files needed for your
+    boards platforms.
 - `daemon` - options related to running Arduino CLI as a [gRPC] server.
   - `port` - TCP port used for gRPC client connections.
 - `directories` - directories used by Arduino CLI.
@@ -67,10 +68,10 @@ Setting an additional Boards Manager URL using the `ARDUINO_BOARD_MANAGER_ADDITI
 $ export ARDUINO_BOARD_MANAGER_ADDITIONAL_URLS=https://downloads.arduino.cc/packages/package_staging_index.json
 ```
 
-Setting an additional Boards Manager URL using the `ARDUINO_BOARD_MANAGER_ADDITIONAL_PATHS` environment variable:
+Setting an additional Boards Manager file using the `ARDUINO_BOARD_MANAGER_ADDITIONAL_PATHS` environment variable:
 
 ```sh
-$ export ARDUINO_BOARD_MANAGER_ADDITIONAL_PATHS=packages/package_staging_index.json
+$ export ARDUINO_BOARD_MANAGER_ADDITIONAL_PATHS=/path/to/your/package_staging_index.json
 ```
 
 ### Configuration file
@@ -135,6 +136,21 @@ Doing the same using a TOML format file:
 additional_urls = [ "https://downloads.arduino.cc/packages/package_staging_index.json" ]
 ```
 
+Setting an additional Boards Manager File using a YAML format configuration file:
+
+```yaml
+board_manager:
+  additional_paths:
+    - /path/to/your/package_staging_index.json
+```
+
+Doing the same using a TOML format file:
+
+```toml
+[board_manager]
+additional_paths = [ "/path/to/your/package_staging_index.json" ]
+```
+
 [grpc]: https://grpc.io
 [sketchbook directory]: sketch-specification.md#sketchbook
 [arduino cli lib install]: commands/arduino-cli_lib_install.md

docs/getting-started.md

@@ -177,12 +177,24 @@ board_manager:
     - https://arduino.esp8266.com/stable/package_esp8266com_index.json
 ```
 
-From now on, commands supporting custom cores will automatically use the additional URL from the configuration file:
+If you have your package indexes locally installed, you can list their file path in the Arduino CLI configuration file.
+
+For example, to add the NRF52832 core, edit the configuration file and change the `board_manager` settings as follows:
+
+```yaml
+board_manager:
+  additional_paths:
+    - /absolute/path/to/your/package_nrf52832_index.json
+```
+
+From now on, commands supporting custom cores will automatically use the additional URL and additional paths from the
+configuration file:
 
 ```sh
 $ arduino-cli core update-index
 Updating index: package_index.json downloaded
 Updating index: package_esp8266com_index.json downloaded
+Updating index: package_nrf52832_index.json
 Updating index: package_index.json downloaded
 
 $ arduino-cli core search esp8266
@@ -202,6 +214,18 @@ ID              Version Name
 esp8266:esp8266 2.5.2   esp8266
 ```
 
+The same applies to the additional package index file provided by file paths. Use the `--additional-paths` option, that
+has to be specified every time and for every command that operates on a 3rd party platform core, for example:
+
+```sh
+$ arduino-cli  core update-index --additional-paths /absolute/path/to/your/package_esp8266com_index.json
+Updating index: package_esp8266com_index.json downloaded
+
+$ arduino-cli core search esp8266 --additional-paths /absolute/path/to/your/package_esp8266com_index.json
+ID              Version Name
+esp8266:esp8266 2.5.2   esp8266
+```
+
 ## Compile and upload the sketch
 
 To compile the sketch you run the `compile` command, passing the proper FQBN string: