doc: update documentation to use the --shield west build command arg

Update zephyr-app-commands to generate "west build --shield ..." for west
invocations using shields while still generating "cmake .. -DSHIELD=..."
if the tool is set to "cmake".

Updated the various shield documentation pages to recommend using
"--shields" over "-DSHIELD" to match the results of the corresponding
zephyr-app-commands code snippets.

Add proper support to zephyr-app-commands for specifying multiple shields
(using a comma-separated list) and fix a few invocations to use this.

Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>

boards/shields/adafruit_2_8_tft_touch_v2/doc/index.rst

@@ -57,7 +57,7 @@ GPIO interfaces (see :ref:`shields` for more details).
 Programming
 ***********
 
-Set ``-DSHIELD=adafruit_2_8_tft_touch_v2`` when you invoke ``west build``. For example:
+Set ``--shield adafruit_2_8_tft_touch_v2`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/display/lvgl
@@ -66,7 +66,7 @@ Set ``-DSHIELD=adafruit_2_8_tft_touch_v2`` when you invoke ``west build``. For e
    :goals: build
 
 If the shield is connected to a board which has Arduino Nano connector,
-set ``-DSHIELD=adafruit_2_8_tft_touch_v2_nano`` when you invoke ``west build``.
+set ``--shield adafruit_2_8_tft_touch_v2_nano`` when you invoke ``west build``.
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/display/lvgl

boards/shields/adafruit_data_logger/doc/index.rst

@@ -62,7 +62,7 @@ defines node aliases for SPI and GPIO interfaces (see :ref:`shields` for more de
 Programming
 ***********
 
-Set ``-DSHIELD=adafruit_data_logger`` when you invoke ``west build``. For example:
+Set ``--shield adafruit_data_logger`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: tests/drivers/rtc/rtc_api

boards/shields/adafruit_neopixel_grid_bff/doc/index.rst

@@ -36,7 +36,7 @@ Programming
 LED Strip Example
 =================
 
-Set ``-DSHIELD=adafruit_neopixel_grid_bff`` when you invoke ``west build``. For example:
+Set ``--shield adafruit_neopixel_grid_bff`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/drivers/led_strip
@@ -57,7 +57,7 @@ LED Display Matrix Example
     recommended if all of the LEDs are fully on for any significant amount of
     time.
 
-Set ``-DSHIELD=adafruit_neopixel_grid_bff_display`` when you invoke ``west build``. For example:
+Set ``--shield adafruit_neopixel_grid_bff_display`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/drivers/display

boards/shields/adafruit_pca9685/doc/index.rst

@@ -27,7 +27,7 @@ Pins Assignments
 Programming
 ***********
 
-Set ``-DSHIELD=adafruit_pca9685`` when you invoke ``west build``.
+Set ``--shield adafruit_pca9685`` when you invoke ``west build``.
 For example:
 
 .. zephyr-app-commands::

boards/shields/adafruit_winc1500/doc/index.rst

@@ -53,7 +53,7 @@ for Arduino connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=adafruit_winc1500`` when you invoke ``west build``. For example:
+Set ``--shield adafruit_winc1500`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/wifi

boards/shields/amg88xx/doc/index.rst

@@ -145,7 +145,7 @@ The ``samples/sensor/amg88xx`` application demonstrates the basic usage of the
 Panasonic Grid-EYE sensor.
 
 If you want to build the application you have to use the
-``-DSHIELD=amg88xx_grid_eye_eval_shield`` shield designation accordingly when
+``--shield amg88xx_grid_eye_eval_shield`` shield designation accordingly when
 you invoke ``west build``.
 
 When using the PAN1780 evaluation board the build invocation looks like this:

boards/shields/arceli_eth_w5500/doc/index.rst

@@ -39,7 +39,7 @@ Arduino header or custom header (by adjusting the overlay).
 Programming
 ***********
 
-Set ``-DSHIELD=arceli_eth_w5500`` when you invoke ``west build``. For example:
+Set ``--shield arceli_eth_w5500`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/dhcpv4_client

boards/shields/arduino_uno_click/doc/index.rst

@@ -38,7 +38,7 @@ socket is assigned the ``mikrobus_header`` node label.
 Programming
 ***********
 
-Include ``-DSHIELD=arduino_uno_click`` when you invoke ``west build`` with
+Include ``--shield arduino_uno_click`` when you invoke ``west build`` with
 other mikroBUS shields. For example:
 
 .. zephyr-app-commands::
@@ -46,7 +46,7 @@ other mikroBUS shields. For example:
    :host-os: unix
    :board: sam_v71_xult/samv71q21
    :gen-args: -DOVERLAY_CONFIG=overlay-802154.conf
-   :shield: "arduino_uno_click atmel_rf2xx_mikrobus"
+   :shield: arduino_uno_click,atmel_rf2xx_mikrobus
    :goals: build
 
 References

boards/shields/atmel_rf2xx/doc/index.rst

@@ -289,7 +289,7 @@ config file. See :zephyr:code-sample:`sockets-echo-server` and
 Build and Programming
 *********************
 
-Set ``-DSHIELD=<shield designator>`` when you invoke ``west build``.
+Set ``--shield <shield designator>`` when you invoke ``west build``.
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/sockets/echo_server

boards/shields/boostxl_ulpsense/doc/index.rst

@@ -23,7 +23,7 @@ BoosterPack connectors.
 Programming
 ***********
 
-Set ``-DSHIELD=boostxl_ulpsense`` when you invoke ``west build``. For example:
+Set ``--shield boostxl_ulpsense`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/sensor/accel_polling/

boards/shields/buydisplay_2_8_tft_touch_arduino/doc/index.rst

@@ -56,7 +56,7 @@ for Arduino connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=buydisplay_2_8_tft_touch_arduino`` when you invoke
+Set ``--shield buydisplay_2_8_tft_touch_arduino`` when you invoke
 ``west build``. For example:
 
 .. zephyr-app-commands::

boards/shields/buydisplay_3_5_tft_touch_arduino/doc/index.rst

@@ -58,7 +58,7 @@ for Arduino connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=buydisplay_3_5_tft_touch_arduino`` when you invoke
+Set ``--shield buydisplay_3_5_tft_touch_arduino`` when you invoke
 ``west build``. For example:
 
 .. zephyr-app-commands::

boards/shields/dvp_fpc24_mt9m114/doc/index.rst

@@ -75,7 +75,7 @@ connector with DVP (parallel) interface, such as the i.MX RT1050, RT1060, RT1064
 Programming
 ***********
 
-Set ``-DSHIELD=dvp_fpc24_mt9m114`` when you invoke ``west build``. For example:
+Set ``--shield dvp_fpc24_mt9m114`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/video/capture

boards/shields/esp_8266/doc/index.rst

@@ -110,7 +110,7 @@ configurations should be used based on the board standard headers available.
 Build and Programming
 *********************
 
-Set ``-DSHIELD=<shield designation>`` when you invoke ``west build``.
+Set ``--shield <shield designation>`` when you invoke ``west build``.
 
 To build shield with specific overlay:
 

boards/shields/frdm_cr20a/doc/index.rst

@@ -52,7 +52,7 @@ For more information about the MCR20A SoC and FRDM-CR20A board:
 Programming
 ***********
 
-Set ``-DSHIELD=frdm_cr20a`` when you invoke ``west build``. For example:
+Set ``--shield frdm_cr20a`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/wpanusb

boards/shields/frdm_kw41z/doc/index.rst

@@ -55,7 +55,7 @@ host controller interface (HCI):
 #. Attach the FRDM-KW41Z to the Arduino header on your selected main board,
    such as :ref:`mimxrt1050_evk` or :ref:`frdm_k64f`.
 
-#. Set ``-DSHIELD=frdm_kw41z`` when you invoke ``west build`` in
+#. Set ``--shield frdm_kw41z`` when you invoke ``west build`` in
    your Zephyr bluetooth application. For example,
 
    .. zephyr-app-commands::

boards/shields/frdm_stbc_agm01/doc/index.rst

@@ -52,7 +52,7 @@ board:
 Programming
 ***********
 
-Set ``-DSHIELD=frdm_stbc_agm01`` when you invoke ``west build``. For example:
+Set ``--shield frdm_stbc_agm01`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/sensor/fxas21002

boards/shields/ftdi_vm800c/doc/index.rst

@@ -75,7 +75,7 @@ See :zephyr:code-sample:`ft800` sample for details.
 Build and Programming
 *********************
 
-Set ``-DSHIELD=<shield designator>`` when you invoke ``west build``.
+Set ``--shield <shield designator>`` when you invoke ``west build``.
 
 .. zephyr-app-commands::
    :zephyr-app: samples/drivers/misc/ft800

boards/shields/g1120b0mipi/doc/index.rst

@@ -50,7 +50,7 @@ for the 40 pin FPC interface
 Programming
 ***********
 
-Set ``-DSHIELD=g1120b0mipi`` when you invoke ``west build``. For
+Set ``--shield g1120b0mipi`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/inventek_eswifi/doc/index.rst

@@ -147,7 +147,7 @@ connect and send ping.
 Build and Programming
 *********************
 
-Set ``-DSHIELD=<shield designator>`` when you invoke ``west build``.
+Set ``--shield <shield designator>`` when you invoke ``west build``.
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/wifi

boards/shields/lcd_par_s035/doc/index.rst

@@ -22,7 +22,7 @@ enabled.
 Programming
 ***********
 
-Set ``-DSHIELD=lcd_par_s035_8080`` when you invoke ``west build``. For
+Set ``--shield lcd_par_s035_8080`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/link_board_eth/doc/index.rst

@@ -102,7 +102,7 @@ For more information about the link board ETH and ENC424J600:
 Programming
 ***********
 
-Set ``-DSHIELD=link_board_eth`` when you invoke ``west build`` or ``cmake`` in your
+Set ``--shield link_board_eth`` when you invoke ``west build`` or ``cmake`` in your
 Zephyr application. For example:
 
 .. zephyr-app-commands::

boards/shields/lmp90100_evb/doc/index.rst

@@ -41,7 +41,7 @@ Zephyr RTOS includes one sample targeting the LMP90100 EVB:
 Programming
 ***********
 
-Set ``-DSHIELD=lmp90100_evb`` when you invoke ``west build``. For example:
+Set ``--shield lmp90100_evb`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/shields/lmp90100_evb/rtd

boards/shields/ls0xx_generic/doc/index.rst

@@ -88,7 +88,7 @@ for Arduino connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=ls013b7dh03`` when you invoke ``west build``. For example:
+Set ``--shield ls013b7dh03`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/display/lvgl

boards/shields/m5stack_core2_ext/doc/index.rst

@@ -38,7 +38,7 @@ Pins Assignments
 Programming
 ***********
 
-Set ``-DSHIELD=m5stack_core2_ext`` when you invoke ``west build``.
+Set ``--shield m5stack_core2_ext`` when you invoke ``west build``.
 For example:
 
 .. zephyr-app-commands::

boards/shields/max3421e/doc/index.rst

@@ -54,5 +54,5 @@ Pins Assignment of the Shield Connector
 Programming
 ***********
 
-Set ``-DSHIELD=sparkfun_max3421e`` when you invoke ``west build`` or ``cmake``
+Set ``--shield sparkfun_max3421e`` when you invoke ``west build`` or ``cmake``
 in your Zephyr application.

boards/shields/max7219/doc/index.rst

@@ -31,7 +31,7 @@ for Arduino connectors and defines a node alias for the SPI interface
 Programming
 ***********
 
-Set ``-DSHIELD=max7219_8x8`` when you invoke ``west build``. For example:
+Set ``--shield max7219_8x8`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/drivers/display/

boards/shields/mcp2515/doc/index.rst

@@ -339,8 +339,8 @@ For more information about the Adafruit PiCowbell CAN Bus shield:
 Programming
 ***********
 
-Set ``-DSHIELD=dfrobot_can_bus_v2_0`` or ``-DSHIELD=keyestudio_can_bus_ks0411``
+Set ``--shield dfrobot_can_bus_v2_0`` or ``--shield keyestudio_can_bus_ks0411``
-or ``-DSHIELD=adafruit_can_picowbell`` when you invoke ``west build`` or ``cmake`` in your Zephyr application. For
+or ``--shield adafruit_can_picowbell`` when you invoke ``west build`` or ``cmake`` in your Zephyr application. For
 example:
 
 .. zephyr-app-commands::

boards/shields/mikroe_accel13_click/doc/index.rst

@@ -34,7 +34,7 @@ see the following documentation:
 Programming
 ***********
 
-Set ``-DSHIELD=mikro_accel13_click`` when you invoke ``west build``. For
+Set ``--shield mikro_accel13_click`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/mikroe_adc_click/doc/index.rst

@@ -31,7 +31,7 @@ see the following documentation:
 Programming
 ***********
 
-Set ``-DSHIELD=mikro_adc_click`` when you invoke ``west build``. For
+Set ``--shield mikro_adc_click`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/mikroe_eth_click/doc/index.rst

@@ -41,7 +41,7 @@ for Mikro-BUS connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=mikroe_eth_click`` when you invoke ``west build``. For example:
+Set ``--shield mikroe_eth_click`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/net/dhcpv4_client

boards/shields/mikroe_mcp2518fd_click/doc/index.rst

@@ -23,7 +23,7 @@ support level triggered interrupts.
 Programming
 ***********
 
-Set ``-DSHIELD=mikroe_mcp2518fd_click`` when you invoke ``west build``,
+Set ``--shield mikroe_mcp2518fd_click`` when you invoke ``west build``,
 for example:
 
 .. zephyr-app-commands::

boards/shields/mikroe_weather_click/doc/index.rst

@@ -34,7 +34,7 @@ documentation:
 Programming
 ***********
 
-Set ``-DSHIELD=mikroe_weather_click`` when you invoke ``west build``. For
+Set ``--shield mikroe_weather_click`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/mikroe_wifi_bt_click/doc/index.rst

@@ -89,7 +89,7 @@ initial log and last message should be the version of the AT firmware flashed.
 Build and Programming
 *********************
 
-Set ``-DSHIELD=<shield designation>`` when you invoke ``west build``.
+Set ``--shield <shield designation>`` when you invoke ``west build``.
 
 See the example below for lpcxpresso55s69 board using Mikrobus serial:
 

boards/shields/npm1100_ek/doc/index.rst

@@ -33,8 +33,8 @@ supports the Arduino connector. The connections are:
 Usage
 *****
 
-The shield can be used in any application by setting ``SHIELD`` to
+The shield can be used in any application by setting ``--shield npm1100_ek``
-``npm1100_ek``.
+when invoking ``west build``.
 
 References
 **********

boards/shields/npm1300_ek/doc/index.rst

@@ -21,9 +21,9 @@ supports the Arduino connector.
 Usage
 *****
 
-The shield can be used in any application by setting ``SHIELD`` to
+The shield can be used in any application by setting ``--shield npm1300_ek``
-``npm1300_ek``. You can check :ref:`npm1300_ek_sample` for a comprehensive
+when invoking ``west build``. You can check :ref:`npm1300_ek_sample` for a
-sample.
+comprehensive sample.
 
 References
 **********

boards/shields/npm6001_ek/doc/index.rst

@@ -27,9 +27,9 @@ supports the Arduino connector.
 Usage
 *****
 
-The shield can be used in any application by setting ``SHIELD`` to
+The shield can be used in any application by setting ``--shield npm6001_ek``
-``npm6001_ek``. You can check :ref:`npm6001_ek_sample` for a comprehensive
+when invoking ``west build``. You can check :ref:`npm6001_ek_sample` for a
-sample.
+comprehensive sample.
 
 References
 **********

boards/shields/nxp_btb44_ov5640/doc/index.rst

@@ -117,7 +117,7 @@ as above, such as i.MX RT1160 and RT1170 EVK boards.
 Programming
 ***********
 
-Set ``-DSHIELD=nxp_btb44_ov5640`` when you invoke ``west build``. For example:
+Set ``--shield nxp_btb44_ov5640`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/video/capture

boards/shields/rk043fn02h_ct/doc/index.rst

@@ -87,7 +87,7 @@ for the 40+6 pin parallel/I2C FPC interface
 Programming
 ***********
 
-Set ``-DSHIELD=rk043fn02h_ct`` when you invoke ``west build``. For
+Set ``--shield rk043fn02h_ct`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/rk043fn66hs_ctg/doc/index.rst

@@ -87,7 +87,7 @@ for the 40+6 pin parallel/I2C FPC interface
 Programming
 ***********
 
-Set ``-DSHIELD=rk043fn66hs_ctg`` when you invoke ``west build``. For
+Set ``--shield rk043fn66hs_ctg`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/rk055hdmipi4m/doc/index.rst

@@ -50,7 +50,7 @@ for the 40 pin FPC interface
 Programming
 ***********
 
-Set ``-DSHIELD=rk055hdmipi4m`` when you invoke ``west build``. For
+Set ``--shield rk055hdmipi4m`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/rk055hdmipi4ma0/doc/index.rst

@@ -50,7 +50,7 @@ for the 40 pin FPC interface
 Programming
 ***********
 
-Set ``-DSHIELD=rk055hdmipi4ma0`` when you invoke ``west build``. For
+Set ``--shield rk055hdmipi4ma0`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/rpi_pico_uno_flexypin/doc/index.rst

@@ -71,7 +71,7 @@ Pins Assignment of the RaspberryPi Pico to UNO FlexyPin Adapter
 Programming
 ***********
 
-Set ``-DSHIELD=rpi_pico_uno_flexypin`` when you invoke ``west build``.
+Set ``--shield rpi_pico_uno_flexypin`` when you invoke ``west build``.
 This shield is just a converter, so it is usually used with other Arduino shield.
 
 For example,
@@ -79,7 +79,7 @@ For example,
 .. zephyr-app-commands::
    :zephyr-app:  samples/net/wifi
    :board: rpi_pico
-   :shield: 'rpi_pico_uno_flexypin;esp_8266_arduino'
+   :shield: rpi_pico_uno_flexypin,esp_8266_arduino
    :goals: build
 
 References

boards/shields/seeed_xiao_expansion_board/doc/index.rst

@@ -53,7 +53,7 @@ Programming
 LED Button Sample
 =================
 
-Set ``-DSHIELD=seeed_xiao_expansion_board`` when you invoke ``west build``. For example:
+Set ``--shield seeed_xiao_expansion_board`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/basic/button
@@ -64,7 +64,7 @@ Set ``-DSHIELD=seeed_xiao_expansion_board`` when you invoke ``west build``. For
 LVGL Basic Sample
 ==========================
 
-Set ``-DSHIELD=seeed_xiao_expansion_board`` when you invoke ``west build``. For example:
+Set ``--shield seeed_xiao_expansion_board`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/display/lvgl

boards/shields/seeed_xiao_round_display/doc/index.rst

@@ -23,7 +23,7 @@ More information can be found on `the Getting Started page`_
 Programming
 ***********
 
-Set ``-DSHIELD=seeed_xiao_round_display`` when you invoke ``west build``.
+Set ``--shield seeed_xiao_round_display`` when you invoke ``west build``.
 
 LVGL Basic Sample
 =================

boards/shields/semtech_sx1262mb2das/doc/index.rst

@@ -47,7 +47,7 @@ for Arduino connectors (see :ref:`shields` for more details).
 Programming
 ***********
 
-Set ``-DSHIELD=semtech_sx1262mb2das`` when you invoke ``west build``. For
+Set ``--shield semtech_sx1262mb2das`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/semtech_sx1272mb2das/doc/index.rst

@@ -50,7 +50,7 @@ for Arduino connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=semtech_sx1272mb2das`` when you invoke ``west build``. For
+Set ``--shield semtech_sx1272mb2das`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/semtech_sx1276mb1mas/doc/index.rst

@@ -58,7 +58,7 @@ Arduino connectors and defines node aliases for SPI and GPIO interfaces (see
 Programming
 ***********
 
-Set ``-DSHIELD=semtech_sx1271mb1mas`` when you invoke ``west build``. For
+Set ``--shield semtech_sx1271mb1mas`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/sparkfun_carrier_asset_tracker/doc/index.rst

@@ -97,7 +97,7 @@ Micromod connectors and defines node aliases for UART, I2C and SPI interfaces (s
 Programming
 ***********
 
-Set ``-DSHIELD=sparkfun_carrier_asset_tracker`` when you invoke ``west build``. For
+Set ``--shield sparkfun_carrier_asset_tracker`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::

boards/shields/ssd1306/doc/index.rst

@@ -38,7 +38,7 @@ for Arduino connectors and defines a node alias for the I2C interface
 Programming
 ***********
 
-Set ``-DSHIELD=ssd1306_128x64`` when you invoke ``west build``. For example:
+Set ``--shield ssd1306_128x64`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/display/lvgl

boards/shields/st7735r/doc/index.rst

@@ -50,7 +50,7 @@ for Arduino connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=st7735r_ada_160x128`` when you invoke ``west build``. For example:
+Set ``--shield st7735r_ada_160x128`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/display/lvgl

boards/shields/st7789v_generic/doc/index.rst

@@ -53,7 +53,7 @@ for Arduino connectors and defines node aliases for SPI and GPIO interfaces
 Programming
 ***********
 
-Set ``-DSHIELD=st7789v_tl019fqv01`` when you invoke ``west build``. For example:
+Set ``--shield st7789v_tl019fqv01`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/display/lvgl

boards/shields/st_b_lcd40_dsi1_mb1166/doc/index.rst

@@ -107,7 +107,7 @@ The shield can be used in any application by setting ``SHIELD`` to
 ``st_b_lcd40_dsi1_mb1166`` or ``st_b_lcd40_dsi1_mb1166_a09`` and adding
 the necessary device tree properties.
 
-Set ``-DSHIELD="st_b_lcd40_dsi1_mb1166"`` when you invoke ``west build``. For example:
+Set ``--shield "st_b_lcd40_dsi1_mb1166"`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/drivers/display

boards/shields/tcan4550evm/doc/index.rst

@@ -53,7 +53,7 @@ Pin Assignments
 Programming
 ***********
 
-Set ``-DSHIELD=tcan4550evm`` when you invoke ``west build``. For example:
+Set ``--shield tcan4550evm`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: tests/drivers/can/api

boards/shields/waveshare_ups/doc/index.rst

@@ -121,7 +121,7 @@ For more information about the Waveshare Pico UPS-B:
 Programming
 ***********
 
-Set ``-DSHIELD=waveshare_pico_ups_b`` when you invoke ``west build`` or ``cmake`` in your Zephyr application. For
+Set ``--shield waveshare_pico_ups_b`` when you invoke ``west build`` or ``cmake`` in your Zephyr application. For
 example:
 
 .. zephyr-app-commands::

boards/shields/x_nucleo_53l0a1/doc/index.rst

@@ -67,7 +67,7 @@ sensors (soldered + 2 satellites) and the 7 segments display.
 Programming
 ***********
 
-Set ``-DSHIELD=x_nucleo_53l0a1`` when you invoke ``west build``. For example:
+Set ``--shield x_nucleo_53l0a1`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/sensor/vl53l0x

boards/shields/x_nucleo_bnrg2a1/doc/index.rst

@@ -64,7 +64,7 @@ Programming
 
 You can use the X-NUCLEO-BNRG2A1 as a Bluetooth Low-Energy controller
 shield with an SPI host controller interface (HCI-SPI).  Activate the presence
-of the shield for the project build by adding the ``-DSHIELD`` arg to the
+of the shield for the project build by adding the ``--shield`` arg to the
 build command:
 
  .. zephyr-app-commands::

boards/shields/x_nucleo_eeprma2/doc/index.rst

@@ -58,7 +58,7 @@ which can be overwritten to use the other EEPROM devices instead.
 Programming
 ***********
 
-Set ``-DSHIELD=x_nucleo_eeprma2`` when you invoke ``west build``. For example:
+Set ``--shield x_nucleo_eeprma2`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
    :zephyr-app: samples/drivers/eeprom/

boards/shields/x_nucleo_idb05a1/doc/index.rst

@@ -74,7 +74,7 @@ Programming
 
 You can use the X-NUCLEO-IDB05A1 as a Bluetooth Low-Energy controller
 shield with an SPI host controller interface (HCI-SPI).  Activate the presence
-of the shield for the project build by adding the ``-DSHIELD`` arg to the
+of the shield for the project build by adding the ``--shield`` arg to the
 build command:
 
  .. zephyr-app-commands::

doc/_extensions/zephyr/application.py

@@ -57,6 +57,7 @@ class ZephyrAppCommandsDirective(Directive):
 
     \:shield:
       if set, the application build will target the given shield.
+      Multiple shields can be provided in a comma separated list.
 
     \:conf:
       if set, the application build will use the given configuration
@@ -200,6 +201,9 @@ class ZephyrAppCommandsDirective(Directive):
         # Create snippet array
         snippet_list = snippets.split(',') if snippets is not None else None
 
+        # Create shields array
+        shield_list = shield.split(',') if shield is not None else None
+
         # Build the command content as a list, then convert to string.
         content = []
         tool_comment = None
@@ -212,7 +216,7 @@ class ZephyrAppCommandsDirective(Directive):
             'in_tree': in_tree,
             'cd_into': cd_into,
             'board': board,
-            'shield': shield,
+            'shield': shield_list,
             'conf': conf,
             'gen_args': gen_args,
             'build_args': build_args,
@@ -274,6 +278,7 @@ class ZephyrAppCommandsDirective(Directive):
         build_dir = kwargs['build_dir']
         build_dir_fmt = kwargs['build_dir_fmt']
         compact = kwargs['compact']
+        shield = kwargs['shield']
         snippets = kwargs['snippets']
         west_args = kwargs['west_args']
         flash_args = kwargs['flash_args']
@@ -285,6 +290,7 @@ class ZephyrAppCommandsDirective(Directive):
         west_args = ' {}'.format(west_args) if west_args else ''
         flash_args = ' {}'.format(flash_args) if flash_args else ''
         snippet_args = ''.join(f' -S {s}' for s in snippets) if snippets else ''
+        shield_args = ''.join(f' --shield {s}' for s in shield) if shield else ''
         # ignore zephyr_app since west needs to run within
         # the installation. Instead rely on relative path.
         src = ' {}'.format(app) if app and not cd_into else ''
@@ -314,8 +320,8 @@ class ZephyrAppCommandsDirective(Directive):
         # defaulting to west.
         #
         # For now, this keeps the resulting commands working.
-        content.append('west build -b {}{}{}{}{}{}'.
+        content.append('west build -b {}{}{}{}{}{}{}'.
-                       format(board, west_args, snippet_args, build_dst, src, cmake_args))
+                       format(board, west_args, snippet_args, shield_args, build_dst, src, cmake_args))
 
         # If we're signing, we want to do that next, so that flashing
         # etc. commands can use the signed file which must be created
@@ -356,15 +362,13 @@ class ZephyrAppCommandsDirective(Directive):
     @staticmethod
     def _cmake_args(**kwargs):
         board = kwargs['board']
-        shield = kwargs['shield']
         conf = kwargs['conf']
         gen_args = kwargs['gen_args']
         board_arg = ' -DBOARD={}'.format(board) if board else ''
-        shield_arg = ' -DSHIELD={}'.format(shield) if shield else ''
         conf_arg = ' -DCONF_FILE={}'.format(conf) if conf else ''
         gen_args = ' {}'.format(gen_args) if gen_args else ''
 
-        return '{}{}{}{}'.format(board_arg, shield_arg, conf_arg, gen_args)
+        return '{}{}{}'.format(board_arg, conf_arg, gen_args)
 
     def _cd_into(self, mkdir, **kwargs):
         app = kwargs['app']
@@ -411,6 +415,7 @@ class ZephyrAppCommandsDirective(Directive):
         build_dir = kwargs['build_dir']
         build_args = kwargs['build_args']
         snippets = kwargs['snippets']
+        shield = kwargs['shield']
         skip_config = kwargs['skip_config']
         goals = kwargs['goals']
         compact = kwargs['compact']
@@ -437,6 +442,7 @@ class ZephyrAppCommandsDirective(Directive):
         gen_arg = ' -GNinja' if generator == 'ninja' else ''
         build_args = ' {}'.format(build_args) if build_args else ''
         snippet_args = ' -DSNIPPET="{}"'.format(';'.join(snippets)) if snippets else ''
+        shield_args = ' -DSHIELD="{}"'.format(';'.join(shield)) if shield else ''
         cmake_args = self._cmake_args(**kwargs)
 
         if not compact:
@@ -448,8 +454,8 @@ class ZephyrAppCommandsDirective(Directive):
                 content.append('# Use cmake to configure a {}-based build' \
                                'system:'.format(generator.capitalize()))  # noqa: E501
 
-        content.append('cmake{}{}{}{}{}'.format(cmake_build_dir, gen_arg,
+        content.append('cmake{}{}{}{}{}{}'.format(cmake_build_dir, gen_arg,
-                                              cmake_args, snippet_args, source_dir))
+                                              cmake_args, snippet_args, shield_args, source_dir))
         if not compact:
             content.extend(['',
                             '# Now run the build tool on the generated build system:'])

doc/hardware/porting/shields.rst

@@ -90,12 +90,12 @@ board or board revision overriding files to a shield, as follows:
 Shield activation
 *****************
 
-Activate support for one or more shields by adding the matching -DSHIELD arg to
+Activate support for one or more shields by adding the matching ``--shield`` arguments
-CMake command
+to the west command:
 
   .. zephyr-app-commands::
      :zephyr-app: your_app
-     :shield: "x_nucleo_idb05a1 x_nucleo_iks01a1"
+     :shield: x_nucleo_idb05a1,x_nucleo_iks01a1
      :goals: build
 
 

samples/subsys/video/capture/README.rst

@@ -43,7 +43,7 @@ For :ref:`mimxrt1064_evk`, build this sample application with the following comm
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/video/capture
    :board: mimxrt1064_evk
-   :shield: "dvp_fpc24_mt9m114 rk043fn66hs_ctg"
+   :shield: dvp_fpc24_mt9m114,rk043fn66hs_ctg
    :goals: build
    :compact:
 
@@ -52,7 +52,7 @@ For :ref:`mimxrt1170_evk`, build this sample application with the following comm
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/video/capture
    :board: mimxrt1170_evk/mimxrt1176/cm7
-   :shield: "nxp_btb44_ov5640 rk055hdmipi4ma0"
+   :shield: nxp_btb44_ov5640,rk055hdmipi4ma0
    :goals: build
    :compact:
 

samples/subsys/video/tcpserversink/README.rst

@@ -35,7 +35,7 @@ If a mt9m114 camera shield is missing, video software generator will be used ins
 .. zephyr-app-commands::
    :zephyr-app: samples/subsys/video/tcpserversink
    :board: mimxrt1064_evk
-   :shield: [dvp_fpc24_mt9m114]
+   :shield: dvp_fpc24_mt9m114
    :goals: build
    :compact: