doc: :zephyr-app: should point to existing in-tree folders

As there is no check (yet!) in the directive, many .. zephyr-app-commands:: in the documentation are pointing to non-existing sample applications, which is problematic for users who typically expect to just copy-paste the commands and have them work. This commit fixes all offending references to point to existing samples, or converts them to simple ":app:" instead of ":zephyr-app:" when the intent wasn't to refer to in-tree samples. Signed-off-by: Benjamin Cabé <[email protected]>
jurenat · Sep 9, 2024 · 25fa25a · 25fa25a
1 parent 7b19f66
commit 25fa25a
Show file tree

Hide file tree

Showing 29 changed files with 46 additions and 43 deletions.
diff --git a/boards/bcdevices/plt_demo_v2/doc/index.rst b/boards/bcdevices/plt_demo_v2/doc/index.rst
@@ -125,15 +125,15 @@ an external programmer. The programmer is attached to the SWD header.
 Build the Zephyr kernel and the :zephyr:code-sample:`led-strip` sample application.
 
    .. zephyr-app-commands::
-      :zephyr-app: samples/drivers/led/apa102
+      :zephyr-app: samples/drivers/led/led_strip
       :board: blueclover_plt_demo_v2/nrf52832
       :goals: build
       :compact:
 
 Flash the image.
 
    .. zephyr-app-commands::
-      :zephyr-app: samples/drivers/led/apa102
+      :zephyr-app: samples/drivers/led/led_strip
       :board: blueclover_plt_demo_v2/nrf52832
       :goals: flash
       :compact:

diff --git a/boards/nxp/frdm_mcxn947/doc/index.rst b/boards/nxp/frdm_mcxn947/doc/index.rst
@@ -211,16 +211,17 @@ Flashing to QSPI
 Here is an example for the :ref:`hello_world` application.
 
 .. zephyr-app-commands::
-   :zephyr-app: zephyr/samples/hello_world -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\" -DCONFIG_BOOTLOADER_MCUBOOT=y
+   :app: zephyr/samples/hello_world
    :board: frdm_mcxn947/mcxn947/cpu0/qspi
+   :gen-args: -DCONFIG_MCUBOOT_SIGNATURE_KEY_FILE=\"bootloader/mcuboot/root-rsa-2048.pem\" -DCONFIG_BOOTLOADER_MCUBOOT=y
    :goals: flash
 
 
 In order to load Zephyr application from QSPI you should program a bootloader like
 MCUboot bootloader to internal flash. Here are the steps.
 
 .. zephyr-app-commands::
-   :zephyr-app: bootloader/mcuboot/boot/zephyr
+   :app: bootloader/mcuboot/boot/zephyr
    :board: frdm_mcxn947/mcxn947/cpu0/qspi
    :goals: flash
 

diff --git a/boards/phytec/phyboard_lyra/doc/phyboard_lyra_am62xx_m4.rst b/boards/phytec/phyboard_lyra/doc/phyboard_lyra_am62xx_m4.rst
@@ -137,7 +137,7 @@ Debugging
 The board is equipped with an XDS110 JTAG debugger. To debug a binary, utilize the `debug` build target:
 
 .. zephyr-app-commands::
-   :zephyr-app: <my_app>
+   :app: <my_app>
    :board: phyboard_lyra/am6234/m4
    :maybe-skip-config:
    :goals: debug

diff --git a/boards/shields/frdm_cr20a/doc/index.rst b/boards/shields/frdm_cr20a/doc/index.rst
@@ -55,7 +55,7 @@ Programming
 Set ``--shield frdm_cr20a`` when you invoke ``west build``. For example:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/net/wpanusb
+   :zephyr-app: samples/net/wpan_serial
    :board: frdm_k64f
    :shield: frdm_cr20a
    :goals: build

diff --git a/boards/shields/mikroe_accel13_click/doc/index.rst b/boards/shields/mikroe_accel13_click/doc/index.rst
@@ -38,7 +38,7 @@ Set ``--shield mikro_accel13_click`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::
-   :zephyr-app: test/boards/board_shell
+   :zephyr-app: samples/sensor/sensor_shell
    :board: lpcxpresso55s69
    :shield: mikroe_accel13_click
    :goals: build

diff --git a/boards/shields/mikroe_adc_click/doc/index.rst b/boards/shields/mikroe_adc_click/doc/index.rst
@@ -35,7 +35,7 @@ Set ``--shield mikro_adc_click`` when you invoke ``west build``. For
 example:
 
 .. zephyr-app-commands::
-   :zephyr-app: <my_app>
+   :app: <my_app>
    :board: lpcxpresso55s16
    :shield: mikroe_adc_click
    :goals: build

diff --git a/boards/shields/x_nucleo_bnrg2a1/doc/index.rst b/boards/shields/x_nucleo_bnrg2a1/doc/index.rst
@@ -68,7 +68,7 @@ of the shield for the project build by adding the ``--shield`` arg to the
 build command:
 
  .. zephyr-app-commands::
-    :zephyr-app: your_app
+    :app: your_app
     :board: your_board_name
     :shield: x_nucleo_bnrg2a1
     :goals: build

diff --git a/boards/shields/x_nucleo_idb05a1/doc/index.rst b/boards/shields/x_nucleo_idb05a1/doc/index.rst
@@ -78,7 +78,7 @@ of the shield for the project build by adding the ``--shield`` arg to the
 build command:
 
  .. zephyr-app-commands::
-    :zephyr-app: your_app
+    :app: your_app
     :board: your_board_name
     :shield: x_nucleo_idb05a1
     :goals: build

diff --git a/boards/shields/x_nucleo_wb05kn1/doc/index.rst b/boards/shields/x_nucleo_wb05kn1/doc/index.rst
@@ -71,15 +71,15 @@ Activate the presence of the shield for the project build by adding the
 ``west build`` based on UART or SPI interface:
 
  .. zephyr-app-commands::
-    :zephyr-app: your_app
+    :app: your_app
     :board: your_board_name
     :shield: x_nucleo_wb05kn1_uart
     :goals: build
 
 or
 
  .. zephyr-app-commands::
-    :zephyr-app: your_app
+    :app: your_app
     :board: your_board_name
     :shield: x_nucleo_wb05kn1_spi
     :goals: build

diff --git a/boards/ti/cc3220sf_launchxl/doc/index.rst b/boards/ti/cc3220sf_launchxl/doc/index.rst
@@ -172,7 +172,7 @@ Flashing
 To build and flash an application, execute the following commands for <my_app>:
 
 .. zephyr-app-commands::
-   :zephyr-app: <my_app>
+   :app: <my_app>
    :board: cc3220sf_launchxl
    :goals: flash
 
@@ -199,7 +199,7 @@ To debug a previously flashed image, after resetting the board, use the 'debug'
 build target:
 
 .. zephyr-app-commands::
-   :zephyr-app: <my_app>
+   :app: <my_app>
    :board: cc3220sf_launchxl
    :maybe-skip-config:
    :goals: debug

diff --git a/boards/ti/cc3235sf_launchxl/doc/index.rst b/boards/ti/cc3235sf_launchxl/doc/index.rst
@@ -172,7 +172,7 @@ Flashing
 To build and flash an application, execute the following commands for <my_app>:
 
 .. zephyr-app-commands::
-   :zephyr-app: <my_app>
+   :app: <my_app>
    :board: cc3235sf_launchxl
    :goals: flash
 
@@ -199,7 +199,7 @@ To debug a previously flashed image, after resetting the board, use the 'debug'
 build target:
 
 .. zephyr-app-commands::
-   :zephyr-app: <my_app>
+   :app: <my_app>
    :board: cc3235sf_launchxl
    :maybe-skip-config:
    :goals: debug

diff --git a/boards/ti/sk_am62/doc/index.rst b/boards/ti/sk_am62/doc/index.rst
@@ -125,7 +125,7 @@ Debugging
 The board is equipped with an XDS110 JTAG debugger. To debug a binary, utilize the `debug` build target:
 
 .. zephyr-app-commands::
-   :zephyr-app: <my_app>
+   :app: <my_app>
    :board: sk_am62/am6234/m4
    :maybe-skip-config:
    :goals: debug

diff --git a/doc/develop/debug/index.rst b/doc/develop/debug/index.rst
@@ -225,7 +225,7 @@ Generate and Import an Eclipse Project
 
    .. zephyr-app-commands::
       :tool: all
-      :zephyr-app: samples\synchronization
+      :zephyr-app: samples/synchronization
       :host-os: win
       :board: frdm_k64f
       :gen-args: -G"Eclipse CDT4 - Ninja"

diff --git a/doc/hardware/emulator/bus_emulators.rst b/doc/hardware/emulator/bus_emulators.rst
@@ -184,7 +184,7 @@ Here are some examples present in Zephyr:
 #. Bosch BMI160 sensor driver connected via both I2C and SPI to an emulator:
 
    .. zephyr-app-commands::
-      :zephyr-app: tests/drivers/sensor/accel/
+      :zephyr-app: tests/drivers/sensor/bmi160
       :board: native_sim
       :goals: build
 

diff --git a/doc/hardware/porting/shields.rst b/doc/hardware/porting/shields.rst
@@ -111,7 +111,7 @@ Activate support for one or more shields by adding the matching ``--shield`` arg
 to the west command:
 
   .. zephyr-app-commands::
-     :zephyr-app: your_app
+     :app: your_app
      :shield: x_nucleo_idb05a1,x_nucleo_iks01a1
      :goals: build
 
@@ -139,7 +139,7 @@ possible to provide multiple version of the shields description:
 In this case, a shield-particular revision name can be used:
 
   .. zephyr-app-commands::
-     :zephyr-app: your_app
+     :app: your_app
      :shield: shield_v2
      :goals: build
 

diff --git a/samples/boards/google_twinkie_v2_pda/README.rst b/samples/boards/google_twinkie_v2_pda/README.rst
@@ -15,7 +15,7 @@ Building and Running
 Build and flash Twinkie as follows:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/boards/google_pda
+   :zephyr-app: samples/boards/google_twinkie_v2_pda
    :board: google_twinkie_v2
    :goals: build flash
    :compact:

diff --git a/samples/boards/stm32/i2c_timing/README.rst b/samples/boards/stm32/i2c_timing/README.rst
@@ -45,7 +45,7 @@ In order to run this sample, make sure to
 - alias the **i2c-0** to your ``i2c`` node of the board **overlay** file
 
  .. zephyr-app-commands::
-   :zephyr-app: samples/boards/stm32/i2c_config
+   :zephyr-app: samples/boards/stm32/i2c_timing
    :board: b_u585i_iot02a
    :goals: build
    :compact:

diff --git a/samples/drivers/i2c/custom_target/README.rst b/samples/drivers/i2c/custom_target/README.rst
@@ -20,12 +20,12 @@ This sample has been tested on :ref:`lpcxpresso55s69`.
 Building and Running
 ********************
 
-The code for this sample can be found in :zephyr_file:`samples/drivers/i2c_target`.
+The code for this sample can be found in :zephyr_file:`samples/drivers/i2c/custom_target`.
 
 To build and flash the application:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/drivers/i2c_target
+   :zephyr-app: samples/drivers/i2c/custom_target
    :board: lpcxpresso55s69/lpc55s69/cpu0
    :goals: flash
    :compact:
diff --git a/samples/drivers/i2c/target_eeprom/README.rst b/samples/drivers/i2c/target_eeprom/README.rst
@@ -20,12 +20,12 @@ This sample has been tested on :ref:`lpcxpresso55s69`.
 Building and Running
 ********************
 
-The code for this sample can be found in :zephyr_file:`samples/drivers/i2c_target`.
+The code for this sample can be found in :zephyr_file:`samples/drivers/i2c/target_eeprom`.
 
 To build and flash the application:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/drivers/i2c_target
+   :zephyr-app: samples/drivers/i2c/target_eeprom
    :board: lpcxpresso55s69/lpc55s69/cpu0
    :goals: flash
    :compact:
diff --git a/samples/drivers/led/is31fl3194/README.rst b/samples/drivers/led/is31fl3194/README.rst
@@ -18,7 +18,7 @@ any board where the devicetree has an I2C device node with compatible
 controller node also being enabled.
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/drivers/led/issi_is31fl3194
+   :zephyr-app: samples/drivers/led/is31fl3194
    :board: arduino_nicla_sense_me
    :goals: build flash
    :compact:

diff --git a/samples/drivers/lora/receive/README.rst b/samples/drivers/lora/receive/README.rst
@@ -25,7 +25,7 @@ Build and flash the sample as follows, changing ``b_l072z_lrwan1`` for
 your board, where your board has a ``lora0`` alias in the devicetree.
 
 .. zephyr-app-commands::
-   :zephyr-app: zephyr/samples/drivers/lora/receive
+   :zephyr-app: samples/drivers/lora/receive
    :host-os: unix
    :board: b_l072z_lrwan1
    :goals: build flash

diff --git a/samples/drivers/lora/send/README.rst b/samples/drivers/lora/send/README.rst
@@ -21,7 +21,7 @@ Build and flash the sample as follows, changing ``b_l072z_lrwan1`` for
 your board, where your board has a ``lora0`` alias in the devicetree.
 
 .. zephyr-app-commands::
-   :zephyr-app: zephyr/samples/drivers/lora/send
+   :zephyr-app: samples/drivers/lora/send
    :host-os: unix
    :board: b_l072z_lrwan1
    :goals: build flash

diff --git a/samples/drivers/smbus/README.rst b/samples/drivers/smbus/README.rst
@@ -18,7 +18,7 @@ Zephyr tree.
 The sample can be built and run as follows for the ``qemu_x86_64`` board:
 
 .. zephyr-app-commands::
-   :zephyr-app: zephyr/samples/drivers/smbus
+   :zephyr-app: samples/drivers/smbus
    :host-os: unix
    :board: qemu_x86_64
    :goals: run

diff --git a/samples/modules/cmsis_dsp/moving_average/README.rst b/samples/modules/cmsis_dsp/moving_average/README.rst
@@ -41,7 +41,7 @@ Building and Running
 The demo can be built as follows:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/modules/cmsis-dsp/moving_average
+   :zephyr-app: samples/modules/cmsis_dsp/moving_average
    :host-os: unix
    :board: qemu_cortex_m0
    :goals: run

diff --git a/samples/modules/compression/lz4/README.rst b/samples/modules/compression/lz4/README.rst
@@ -22,7 +22,7 @@ Add the lz4 module to your West manifest and pull it:
 The sample can be built and executed on nrf52840dk/nrf52840 as follows:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/compression/lz4
+   :zephyr-app: samples/modules/compression/lz4
    :board: nrf52840dk/nrf52840
    :goals: build flash
    :compact:

diff --git a/samples/subsys/mgmt/updatehub/README.rst b/samples/subsys/mgmt/updatehub/README.rst
@@ -73,7 +73,7 @@ documentation page.  Flash the resulting image file using west on
 ``terminal 1``.
 
 .. zephyr-app-commands::
-    :zephyr-app: bootloader/mcuboot/boot/zephyr
+    :app: bootloader/mcuboot/boot/zephyr
     :board: frdm_k64f
     :build-dir: mcuboot-frdm_k64f
     :goals: build flash
@@ -172,7 +172,7 @@ Step 4.1: Build for Ethernet
 The ethernet depends only from base configuration.
 
 .. zephyr-app-commands::
-    :zephyr-app: zephyr/samples/subsys/mgmt/updatehub
+    :zephyr-app: samples/subsys/mgmt/updatehub
     :board: [ frdm_k64f | nucleo_f767zi ]
     :build-dir: app
     :gen-args: -DEXTRA_CONF_FILE=overlay-prj.conf
@@ -187,7 +187,7 @@ connectivity using, for instance, arduino headers.  See :ref:`module_esp_8266`
 for details.
 
 .. zephyr-app-commands::
-    :zephyr-app: zephyr/samples/subsys/mgmt/updatehub
+    :zephyr-app: samples/subsys/mgmt/updatehub
     :board: [ frdm_k64f | nrf52840dk/nrf52840 | nucleo_f767zi ]
     :build-dir: app
     :gen-args: -DEXTRA_CONF_FILE="overlay-wifi.conf;overlay-prj.conf"
@@ -209,15 +209,15 @@ at this moment provide support since it is experimental.  The gateway was
 tested with both native linux driver and ``atusb``.
 
 .. zephyr-app-commands::
-    :zephyr-app: zephyr/samples/subsys/mgmt/updatehub
+    :zephyr-app: samples/subsys/mgmt/updatehub
     :board: nrf52840dk/nrf52840
     :build-dir: app
     :gen-args: -DEXTRA_CONF_FILE="overlay-802154.conf;overlay-prj.conf"
     :goals: build
     :compact:
 
 .. zephyr-app-commands::
-    :zephyr-app: zephyr/samples/subsys/mgmt/updatehub
+    :zephyr-app: samples/subsys/mgmt/updatehub
     :board: [ frdm_k64f | nucleo_f767zi ]
     :build-dir: app
     :gen-args: -DEXTRA_CONF_FILE="overlay-802154.conf;overlay-prj.conf"
@@ -236,7 +236,7 @@ out of scope at this moment provide support since it is experimental.  The
 gateway was tested using two boards with OpenThread 1.1.1 on NCP mode.
 
 .. zephyr-app-commands::
-    :zephyr-app: zephyr/samples/subsys/mgmt/updatehub
+    :zephyr-app: samples/subsys/mgmt/updatehub
     :board: nrf52840dk/nrf52840
     :build-dir: app
     :gen-args: -DEXTRA_CONF_FILE="overlay-ot.conf;overlay-prj.conf"

diff --git a/samples/subsys/smf/hsm_psicc2/README.rst b/samples/subsys/smf/hsm_psicc2/README.rst
@@ -19,7 +19,7 @@ Building and Running for ST Disco L475 IOT01 (B-L475E-IOT01A)
 The sample can be built and executed for the :ref:`disco_l475_iot1_board` as follows:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/subsys/smf/psicc2
+   :zephyr-app: samples/subsys/smf/hsm_psicc2
    :board: disco_l475_iot1
    :goals: build flash
    :compact:

diff --git a/samples/subsys/zbus/priority_boost/README.rst b/samples/subsys/zbus/priority_boost/README.rst
@@ -47,7 +47,8 @@ disabled.
 It can be built and executed on QEMU as follows:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/subsys/zbus/priority_boost -- -DCONFIG_ZBUS_PRIORITY_BOOST=n
+   :zephyr-app: samples/subsys/zbus/priority_boost
+   :gen-args: -DCONFIG_ZBUS_PRIORITY_BOOST=n
    :host-os: unix
    :board: qemu_x86
    :goals: run
@@ -127,7 +128,8 @@ The developer must enable the priority boost and properly attach all the observe
 To execute the sample with priority boost feature enabled, run the following command:
 
 .. zephyr-app-commands::
-   :zephyr-app: samples/subsys/zbus/priority_boost -- -DCONFIG_ZBUS_PRIORITY_BOOST=y
+   :zephyr-app: samples/subsys/zbus/priority_boost
+   :gen-args: -DCONFIG_ZBUS_PRIORITY_BOOST=y
    :host-os: unix
    :board: qemu_x86
    :goals: run

diff --git a/samples/sysbuild/with_mcuboot/README.rst b/samples/sysbuild/with_mcuboot/README.rst
@@ -32,7 +32,7 @@ To build both the sample and MCUboot with ``west`` for the ``reel_board``, run:
 
 .. zephyr-app-commands::
    :tool: west
-   :zephyr-app: samples/application_development/sysbuild/with_mcuboot
+   :zephyr-app: samples/sysbuild/with_mcuboot
    :board: reel_board
    :goals: build
    :west-args: --sysbuild