samples: bluetooth: use zephyr:code-sample directive

Describe the samples using code-sample directive in preparation for upcoming changes to the Zephyr documentation that will be leveraging the provided description and metadata. Signed-off-by: Benjamin Cabé <[email protected]>
zephyrproject-rtos · Aug 30, 2024 · d8032cd · d8032cd
1 parent 40414f7
commit d8032cd
Show file tree

Hide file tree

Showing 90 changed files with 308 additions and 254 deletions.
diff --git a/boards/96boards/carbon/doc/stm32f401xe.rst b/boards/96boards/carbon/doc/stm32f401xe.rst
@@ -347,7 +347,7 @@ in general, see :ref:`build_an_application`.
       :board: 96b_carbon/stm32f401xe
       :goals: build flash
 
-#. Refer to the instructions in :ref:`peripheral_hr` for how
+#. Refer to the instructions in :zephyr:code-sample:`ble_peripheral_hr` for how
    to verify functionality.
 
 Congratulations! Your 96Boards Carbon now has Bluetooth

diff --git a/boards/ezurio/bl5340_dvk/doc/index.rst b/boards/ezurio/bl5340_dvk/doc/index.rst
@@ -410,8 +410,8 @@ Many of the Bluetooth examples will work on the BL5340 DVK.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 References
 **********

diff --git a/boards/ezurio/bl652_dvk/doc/bl652_dvk.rst b/boards/ezurio/bl652_dvk/doc/bl652_dvk.rst
@@ -246,8 +246,8 @@ Many of the Bluetooth examples will work on the BL652 DVK.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 Testing the LEDs and buttons in the BL652 DVK
 *********************************************

diff --git a/boards/ezurio/bl653_dvk/doc/bl653_dvk.rst b/boards/ezurio/bl653_dvk/doc/bl653_dvk.rst
@@ -152,8 +152,8 @@ Many of the Bluetooth examples will work on the BL653 DVK.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 
 Testing the LEDs and buttons on the BL653 DVK

diff --git a/boards/ezurio/bl654_dvk/doc/bl654_dvk.rst b/boards/ezurio/bl654_dvk/doc/bl654_dvk.rst
@@ -163,8 +163,8 @@ Many of the Bluetooth examples will work on the BL654 DVK.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 
 Testing the LEDs and buttons on the BL654 DVK

diff --git a/boards/ezurio/bl654_sensor_board/doc/bl654_sensor_board.rst b/boards/ezurio/bl654_sensor_board/doc/bl654_sensor_board.rst
@@ -223,8 +223,8 @@ Many of the Bluetooth examples will work on the BL654 Sensor Board.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 
 Testing the LED and button on the BL654 Sensor Board

diff --git a/boards/ezurio/bl654_usb/doc/bl654_usb.rst b/boards/ezurio/bl654_usb/doc/bl654_usb.rst
@@ -161,8 +161,8 @@ Many of the Bluetooth examples will work on the BL654 USB.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 
 Testing the LED on the BL654 USB

diff --git a/boards/ezurio/bt510/doc/bt510.rst b/boards/ezurio/bt510/doc/bt510.rst
@@ -229,8 +229,8 @@ Many of the Bluetooth examples will work on the BT510.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 
 Testing the LEDs and buttons on the BT510

diff --git a/boards/ezurio/bt610/doc/bt610.rst b/boards/ezurio/bt610/doc/bt610.rst
@@ -583,8 +583,8 @@ Many of the Bluetooth examples will work on the BT610.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 
 Testing the LEDs and buttons on the BT610

diff --git a/boards/ezurio/mg100/doc/index.rst b/boards/ezurio/mg100/doc/index.rst
@@ -214,8 +214,8 @@ Many of the Bluetooth examples will work on the MG100.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 Testing the LEDs and buttons in the MG100
 ====================================================

diff --git a/boards/ezurio/pinnacle_100_dvk/doc/index.rst b/boards/ezurio/pinnacle_100_dvk/doc/index.rst
@@ -188,8 +188,8 @@ Many of the Bluetooth examples will work on the Pinnacle 100 DVK.
 Try them out:
 
 * :ref:`ble_peripheral`
-* :ref:`bluetooth-eddystone-sample`
-* :ref:`bluetooth-ibeacon-sample`
+* :zephyr:code-sample:`bluetooth_eddystone`
+* :zephyr:code-sample:`bluetooth_ibeacon`
 
 Testing the LEDs and buttons in the Pinnacle 100 DVK
 ====================================================

diff --git a/boards/silabs/dev_kits/sltb010a/doc/index.rst b/boards/silabs/dev_kits/sltb010a/doc/index.rst
@@ -177,7 +177,7 @@ blobs from the SiLabs HAL repository.
    west blobs fetch hal_silabs
 
 Then build the Zephyr kernel and a Bluetooth sample with the following
-command. The :ref:`bluetooth-observer-sample` sample application is used in
+command. The :zephyr:code-sample:`bluetooth_observer` sample application is used in
 this example.
 
 BRD4184A:

diff --git a/boards/silabs/dev_kits/xg24_dk2601b/doc/index.rst b/boards/silabs/dev_kits/xg24_dk2601b/doc/index.rst
@@ -160,7 +160,7 @@ blobs from the SiLabs HAL repository.
    west blobs fetch hal_silabs
 
 Then build the Zephyr kernel and a Bluetooth sample with the following
-command. The :ref:`bluetooth-observer-sample` sample application is used in
+command. The :zephyr:code-sample:`bluetooth_observer` sample application is used in
 this example.
 
 .. zephyr-app-commands::

diff --git a/boards/sparkfun/thing_plus_matter_mgm240p/doc/index.rst b/boards/sparkfun/thing_plus_matter_mgm240p/doc/index.rst
@@ -141,7 +141,7 @@ blobs from the SiLabs HAL repository.
    west blobs fetch silabs
 
 Then build the Zephyr kernel and a Bluetooth sample with the following
-command. The :ref:`bluetooth-observer-sample` sample application is used in
+command. The :zephyr:code-sample:`bluetooth_observer` sample application is used in
 this example.
 
 .. zephyr-app-commands::

diff --git a/boards/st/stm32wb5mmg/doc/stm32wb5mmg.rst b/boards/st/stm32wb5mmg/doc/stm32wb5mmg.rst
@@ -245,7 +245,7 @@ Flashing `hci_uart` application to STM32WB5MMG
 Connect the B-U585I-IOT02A to your host computer using the USB port. Put
 the SW4 (MCU SWD) in OFF mode and SW5 (SWD BLE) in ON mode. Then build
 and flash an application. Here is an example for the
-:ref:`hci_uart <bluetooth-hci-uart-sample>` application.
+:zephyr:code-sample:`bluetooth_hci_uart` application.
 
 Run a serial host program to connect with your B-U585I-IOT02A board:
 
@@ -287,7 +287,7 @@ Debugging
 =========
 
 You can debug an application in the usual way.  Here is an example for the
-:ref:`hci_uart <bluetooth-hci-uart-sample>` application.
+:zephyr:code-sample:`bluetooth_hci_uart` application.
 
 .. zephyr-app-commands::
    :zephyr-app: samples/bluetooth/observer

diff --git a/boards/vngiotlab/nrf51_vbluno51/doc/index.rst b/boards/vngiotlab/nrf51_vbluno51/doc/index.rst
@@ -138,8 +138,8 @@ Testing the VBLUno51 with Zephyr: buttons, LEDs, UART, BLE
  * :ref:`hello_world`
  * :zephyr:code-sample:`blinky`
  * :zephyr:code-sample:`button`
- * :ref:`bluetooth-beacon-sample`
- * :ref:`peripheral_hr`
+ * :zephyr:code-sample:`bluetooth_beacon`
+ * :zephyr:code-sample:`ble_peripheral_hr`
 
 References
 **********

diff --git a/boards/vngiotlab/nrf52_vbluno52/doc/index.rst b/boards/vngiotlab/nrf52_vbluno52/doc/index.rst
@@ -103,5 +103,5 @@ components on the VBLUno52 board:
 * :ref:`hello_world`
 * :zephyr:code-sample:`blinky`
 * :zephyr:code-sample:`button`
-* :ref:`bluetooth-beacon-sample`
-* :ref:`peripheral_hr`
+* :zephyr:code-sample:`bluetooth_beacon`
+* :zephyr:code-sample:`ble_peripheral_hr`
diff --git a/doc/build/dts/api/api.rst b/doc/build/dts/api/api.rst
@@ -382,7 +382,7 @@ device.
      - Purpose
    * - zephyr,bt-c2h-uart
      - Selects the UART used for host communication in the
-       :ref:`bluetooth-hci-uart-sample`
+       :zephyr:code-sample:`bluetooth_hci_uart`
    * - zephyr,bt-mon-uart
      - Sets UART device used for the Bluetooth monitor logging
    * - zephyr,bt-hci

diff --git a/doc/connectivity/bluetooth/bluetooth-arch.rst b/doc/connectivity/bluetooth/bluetooth-arch.rst
@@ -97,9 +97,9 @@ BLE-enabled builds that can be produced from the Zephyr project codebase:
   the Link Layer and a special application. This application is different
   depending on the physical transport chosen for HCI:
 
-  * :ref:`hci_uart <bluetooth-hci-uart-sample>`
-  * :ref:`hci_usb <bluetooth-hci-usb-sample>`
-  * :ref:`hci_spi <bluetooth-hci-spi-sample>`
+  * :zephyr:code-sample:`bluetooth_hci_uart`
+  * :zephyr:code-sample:`bluetooth_hci_usb`
+  * :zephyr:code-sample:`bluetooth_hci_spi`
 
   This application acts as a bridge between the UART, SPI or USB peripherals and
   the Controller subsystem, listening for HCI commands, sending application data
@@ -160,8 +160,8 @@ must be built with different configurations, yielding two separate images that
 must be programmed into each of the chips respectively. The Host build image
 contains the application, the BLE Host and the selected HCI driver (UART or
 SPI), while the Controller build runs either the
-:ref:`hci_uart <bluetooth-hci-uart-sample>`, or the
-:ref:`hci_spi <bluetooth-hci-spi-sample>` app to provide an interface to
+:zephyr:code-sample:`bluetooth_hci_uart`, or the
+:zephyr:code-sample:`bluetooth_hci_spi` app to provide an interface to
 the BLE Controller.
 
 This configuration is not limited to using a Zephyr OS Host, as the right side

diff --git a/doc/connectivity/bluetooth/bluetooth-dev.rst b/doc/connectivity/bluetooth/bluetooth-dev.rst
@@ -153,7 +153,7 @@ devices in either of :ref:`these boards's documentation <nrf52bsim_build_and_run
 
 With the :ref:`nrf52_bsim <nrf52_bsim>`, typically you do :ref:`Combined builds
 <bluetooth-build-types>`, but it is also possible to build the controller with one of the
-:ref:`HCI UART <bluetooth-hci-uart-sample>` samples in one simulated device, and the host with
+:zephyr:code-sample:`bluetooth_hci_uart` samples in one simulated device, and the host with
 the H4 driver instead of the integrated controller in another simulated device.
 
 With the :ref:`nrf5340bsim <nrf5340bsim>`, you can build with either, both controller and host

diff --git a/doc/connectivity/bluetooth/bluetooth-shell.rst b/doc/connectivity/bluetooth/bluetooth-shell.rst
@@ -394,7 +394,7 @@ The server can now notify the client with the command :code:`gatt notify`.
 Another option available through the GATT command is initiating the MTU exchange. To do it, use the
 :code:`gatt exchange-mtu` command. To update the shell maximum MTU, you need to update Kconfig
 symbols in the configuration file of the shell. For more details, see
-:ref:`bluetooth_mtu_update_sample`.
+:zephyr:code-sample:`bluetooth_mtu_update`.
 
 L2CAP
 *****

diff --git a/doc/connectivity/bluetooth/bluetooth-tools.rst b/doc/connectivity/bluetooth/bluetooth-tools.rst
@@ -166,9 +166,9 @@ Using a Zephyr-based BLE Controller
 Depending on which hardware you have available, you can choose between two
 transports when building a single-mode, Zephyr-based BLE Controller:
 
-* UART: Use the :ref:`hci_uart <bluetooth-hci-uart-sample>` sample and follow
+* UART: Use the :zephyr:code-sample:`bluetooth_hci_uart` sample and follow
   the instructions in :ref:`bluetooth-hci-uart-qemu-posix`.
-* USB: Use the :ref:`hci_usb <bluetooth-hci-usb-sample>` sample and then
+* USB: Use the :zephyr:code-sample:`bluetooth_hci_usb` sample and then
   treat it as a Host System Bluetooth Controller (see previous section)
 
 .. _bluetooth-hci-tracing:
@@ -301,7 +301,7 @@ After following these steps the Zephyr application will be available to the Andr
 over the virtual Bluetooth controller that was bridged with Bumble. You can verify that the
 Zephyr application can communicate over Bluetooth by opening the Bluetooth settings in your
 AVD and scanning for your Zephyr application device. To test this you can build the Bluetooth
-peripheral samples such as :ref:`Peripheral HR <peripheral_hr>` or :ref:`Peripheral DIS <peripheral_dis>`
+peripheral samples such as :zephyr:code-sample:`ble_peripheral_hr` or :ref:`Peripheral DIS <peripheral_dis>`
 
 .. _bluetooth_ctlr_bluez:
 

diff --git a/doc/connectivity/usb/device/usb_device.rst b/doc/connectivity/usb/device/usb_device.rst
@@ -64,7 +64,7 @@ the next interface, preventing other composite functions from working.
 Because of this problem, HCI USB should not be used in a composite configuration.
 This problem is fixed in the implementation for new USB support.
 
-See :ref:`bluetooth-hci-usb-sample` sample for reference.
+See :zephyr:code-sample:`bluetooth_hci_usb` sample for reference.
 
 .. _usb_device_cdc_acm:
 
@@ -168,7 +168,7 @@ List of few Zephyr specific chosen properties which can be used to select
 CDC ACM UART as backend for a subsystem or application:
 
 * ``zephyr,bt-c2h-uart`` used in Bluetooth,
-  for example see :ref:`bluetooth-hci-uart-sample`
+  for example see :zephyr:code-sample:`bluetooth_hci_uart`
 * ``zephyr,ot-uart`` used in OpenThread,
   for example see :zephyr:code-sample:`coprocessor`
 * ``zephyr,shell-uart`` used by shell for serial backend,
@@ -595,9 +595,9 @@ The following Product IDs are currently used:
 +----------------------------------------------------+--------+
 | :zephyr:code-sample:`webusb`                       | 0x000A |
 +----------------------------------------------------+--------+
-| :ref:`bluetooth-hci-usb-sample`                    | 0x000B |
+| :zephyr:code-sample:`bluetooth_hci_usb`            | 0x000B |
 +----------------------------------------------------+--------+
-| :ref:`bluetooth-hci-usb-h4-sample`                 | 0x000C |
+| :zephyr:code-sample:`bluetooth_hci_usb_h4`         | 0x000C |
 +----------------------------------------------------+--------+
 | Reserved (previously: wpan-usb)                    | 0x000D |
 +----------------------------------------------------+--------+

diff --git a/doc/connectivity/usb/device_next/usb_device.rst b/doc/connectivity/usb/device_next/usb_device.rst
@@ -64,7 +64,7 @@ To build a sample that supports both the old and new USB device stack, set the
 configuration ``-DCONF_FILE=usbd_next_prj.conf`` either directly or via
 ``west``.
 
-* :ref:`bluetooth-hci-usb-sample`
+* :zephyr:code-sample:`bluetooth_hci_usb`
 
 * :zephyr:code-sample:`usb-cdc-acm`
 

diff --git a/samples/bluetooth/bap_broadcast_assistant/README.rst b/samples/bluetooth/bap_broadcast_assistant/README.rst
@@ -1,8 +1,8 @@
 .. zephyr:code-sample:: bluetooth_bap_broadcast_assistant
-   :name: Bluetooth: Broadcast Audio Assistant
+   :name: Broadcast Audio Assistant
    :relevant-api: bt_bap
 
-   Use LE Audio Broadcast Assistant functionality
+   Use LE Audio Broadcast Assistant functionality.
 
 Overview
 ********

diff --git a/samples/bluetooth/bap_broadcast_sink/README.rst b/samples/bluetooth/bap_broadcast_sink/README.rst
@@ -1,8 +1,8 @@
 .. zephyr:code-sample:: bluetooth_bap_broadcast_sink
-   :name: Bluetooth: Broadcast Audio Sink
+   :name: Broadcast Audio Sink
    :relevant-api: bluetooth
 
-   Bluetooth: Broadcast Audio Sink
+   Use LE Audio Broadcast Sink functionality.
 
 Overview
 ********
@@ -53,7 +53,7 @@ If you prefer to only build the application core image, you can do so by doing i
    :goals: build
 
 In that case you can pair this application core image with the
-:ref:`hci_ipc sample <bluetooth-hci-ipc-sample>`
+:zephyr:code-sample:`bluetooth_hci_ipc` sample
 :zephyr_file:`samples/bluetooth/hci_ipc/nrf5340_cpunet_iso-bt_ll_sw_split.conf` configuration.
 
 Building for a simulated nrf5340bsim

diff --git a/samples/bluetooth/bap_broadcast_source/README.rst b/samples/bluetooth/bap_broadcast_source/README.rst
@@ -1,8 +1,8 @@
 .. zephyr:code-sample:: bluetooth_bap_broadcast_source
-   :name: Bluetooth: Broadcast Audio Source
+   :name: Broadcast Audio Source
    :relevant-api: bluetooth
 
-   Bluetooth: Broadcast Audio Source
+   Use LE Audio Broadcast Source functionality.
 
 Overview
 ********
@@ -52,7 +52,7 @@ If you prefer to only build the application core image, you can do so by doing i
    :goals: build
 
 In that case you can pair this application core image with the
-:ref:`hci_ipc sample <bluetooth-hci-ipc-sample>`
+:zephyr:code-sample:`bluetooth_hci_ipc` sample
 :zephyr_file:`samples/bluetooth/hci_ipc/nrf5340_cpunet_iso-bt_ll_sw_split.conf` configuration.
 
 Building for a simulated nrf5340bsim

diff --git a/samples/bluetooth/bap_unicast_client/README.rst b/samples/bluetooth/bap_unicast_client/README.rst
@@ -1,7 +1,8 @@
-.. _bluetooth_bap_unicast_client:
+.. zephyr:code-sample:: bluetooth_bap_unicast_client
+   :name: Unicast Audio Client
+   :relevant-api: bt_bap bt_audio
 
-Bluetooth: Unicast Audio Client
-###############################
+   Use LE Audio Unicast Client functionality.
 
 Overview
 ********
@@ -56,7 +57,7 @@ If you prefer to only build the application core image, you can do so by doing i
    :goals: build
 
 In that case you can pair this application core image with the
-:ref:`hci_ipc sample <bluetooth-hci-ipc-sample>`
+:zephyr:code-sample:`bluetooth_hci_ipc` sample
 :zephyr_file:`samples/bluetooth/hci_ipc/nrf5340_cpunet_iso-bt_ll_sw_split.conf` configuration.
 
 Building for a simulated nrf52_bsim

diff --git a/samples/bluetooth/bap_unicast_server/README.rst b/samples/bluetooth/bap_unicast_server/README.rst
@@ -1,7 +1,8 @@
-.. _bluetooth_bap_unicast_server:
+.. zephyr:code-sample:: bluetooth_bap_unicast_server
+   :name: Unicast Audio Server
+   :relevant-api: bt_bap bt_audio
 
-Bluetooth: Unicast Audio Server
-###############################
+   Use LE Audio Unicast Server functionality.
 
 Overview
 ********
@@ -56,7 +57,7 @@ If you prefer to only build the application core image, you can do so by doing i
    :goals: build
 
 In that case you can pair this application core image with the
-:ref:`hci_ipc sample <bluetooth-hci-ipc-sample>`
+:zephyr:code-sample:`bluetooth_hci_ipc` sample
 :zephyr_file:`samples/bluetooth/hci_ipc/nrf5340_cpunet_iso-bt_ll_sw_split.conf` configuration.
 
 Building for a simulated nrf52_bsim

diff --git a/samples/bluetooth/beacon/README.rst b/samples/bluetooth/beacon/README.rst
@@ -1,7 +1,8 @@
-.. _bluetooth-beacon-sample:
+.. zephyr:code-sample:: bluetooth_beacon
+   :name: Beacon
+   :relevant-api: bluetooth
 
-Bluetooth: Beacon
-#################
+   Advertise an Eddystone URL using BLE Broadcaster role.
 
 Overview
 ********