doc: samples: Adopt code-sample-category across tree

This commit uses the new .. zephyr:code-sample-category directive to categorize code samples across the tree. Updates existing legacy references to manually defined targets to now use :zephyr:code-sample-category: role instead. Signed-off-by: Benjamin Cabé <[email protected]>
zephyrproject-rtos · Sep 17, 2024 · ad39ade · ad39ade
1 parent f6f4feb
commit ad39ade
Show file tree

Hide file tree

Showing 210 changed files with 573 additions and 766 deletions.
diff --git a/boards/adafruit/feather_m0_basic_proto/doc/index.rst b/boards/adafruit/feather_m0_basic_proto/doc/index.rst
@@ -96,7 +96,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/adafruit/feather_m0_lora/doc/index.rst b/boards/adafruit/feather_m0_lora/doc/index.rst
@@ -99,7 +99,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/adafruit/grand_central_m4_express/doc/index.rst b/boards/adafruit/grand_central_m4_express/doc/index.rst
@@ -98,7 +98,7 @@ USB Device Port
 ===============
 
 The SAMD51 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/adafruit/itsybitsy_m4_express/doc/index.rst b/boards/adafruit/itsybitsy_m4_express/doc/index.rst
@@ -106,7 +106,7 @@ USB Device Port
 ===============
 
 The SAMD51 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/adafruit/trinket_m0/doc/index.rst b/boards/adafruit/trinket_m0/doc/index.rst
@@ -98,7 +98,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/arduino/mkrzero/doc/index.rst b/boards/arduino/mkrzero/doc/index.rst
@@ -111,7 +111,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/arduino/nano_33_iot/doc/index.rst b/boards/arduino/nano_33_iot/doc/index.rst
@@ -102,7 +102,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/arduino/zero/doc/index.rst b/boards/arduino/zero/doc/index.rst
@@ -98,7 +98,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/espressif/esp32_devkitc_wroom/doc/index.rst b/boards/espressif/esp32_devkitc_wroom/doc/index.rst
@@ -54,7 +54,7 @@ Asymmetric Multiprocessing (AMP)
 ********************************
 
 ESP32-DevKitC-WROOM allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
-and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.
+and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference.
 
 Supported Features
 ==================

diff --git a/boards/espressif/esp32_devkitc_wrover/doc/index.rst b/boards/espressif/esp32_devkitc_wrover/doc/index.rst
@@ -54,7 +54,7 @@ Asymmetric Multiprocessing (AMP)
 ********************************
 
 ESP32-DevKitC-WROVER allows 2 different applications to be executed in ESP32 SoC. Due to its dual-core architecture, each core can be enabled to execute customized tasks in stand-alone mode
-and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.
+and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference.
 
 Supported Features
 ==================

diff --git a/boards/espressif/esp32s3_devkitc/doc/index.rst b/boards/espressif/esp32s3_devkitc/doc/index.rst
@@ -76,7 +76,7 @@ Asymmetric Multiprocessing (AMP)
 
 ESP32S3-DevKitC allows 2 different applications to be executed in ESP32-S3 SoC. Due to its dual-core
 architecture, each core can be enabled to execute customized tasks in stand-alone mode
-and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.
+and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference.
 
 For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference
 manual at `ESP32-S3 Technical Reference Manual`_.

diff --git a/boards/espressif/esp32s3_devkitm/doc/index.rst b/boards/espressif/esp32s3_devkitm/doc/index.rst
@@ -76,7 +76,7 @@ Asymmetric Multiprocessing (AMP)
 
 ESP32S3-DevKitM allows 2 different applications to be executed in ESP32-S3 SoC. Due to its dual-core
 architecture, each core can be enabled to execute customized tasks in stand-alone mode
-and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.
+and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference.
 
 For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference
 manual at `ESP32-S3 Technical Reference Manual`_.

diff --git a/boards/openisa/rv32m1_vega/doc/index.rst b/boards/openisa/rv32m1_vega/doc/index.rst
@@ -578,7 +578,7 @@ toolchain and OpenOCD::
    You need to make sure this happens every time you use this board.
 
 Now let's compile the :zephyr:code-sample:`hello_world` application. (You can try
-others as well; see :ref:`samples-and-demos` for more.)
+others as well; see :zephyr:code-sample-category:`samples` for more.)
 
 .. We can't use zephyr-app-commands to provide build instructions
    due to the below mentioned linker issue.

diff --git a/boards/others/serpente/doc/index.rst b/boards/others/serpente/doc/index.rst
@@ -74,7 +74,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which prints "Hello World!"
 to the host PC.
 

diff --git a/boards/seeed/seeeduino_xiao/doc/index.rst b/boards/seeed/seeeduino_xiao/doc/index.rst
@@ -98,7 +98,7 @@ USB Device Port
 ===============
 
 The SAMD21 MCU has a USB device port that can be used to communicate
-with a host PC.  See the :ref:`usb-samples` sample applications for
+with a host PC.  See the :zephyr:code-sample-category:`usb` sample applications for
 more, such as the :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual
 serial port that echos characters back to the host PC.
 

diff --git a/boards/seeed/wio_terminal/doc/index.rst b/boards/seeed/wio_terminal/doc/index.rst
@@ -121,7 +121,7 @@ USB Device Port
 ===============
 
 The SAMD51 MCU has a USB device port that can be used to communicate with a
-host PC.  See the :ref:`usb-samples` sample applications for more, such as the
+host PC.  See the :zephyr:code-sample-category:`usb` sample applications for more, such as the
 :zephyr:code-sample:`usb-cdc-acm` sample which sets up a virtual serial port that echos
 characters back to the host PC.
 

diff --git a/boards/shields/npm1300_ek/doc/index.rst b/boards/shields/npm1300_ek/doc/index.rst
@@ -22,7 +22,7 @@ Usage
 *****
 
 The shield can be used in any application by setting ``--shield npm1300_ek``
-when invoking ``west build``. You can check :ref:`npm1300_ek_sample` for a
+when invoking ``west build``. You can check :zephyr:code-sample:`npm1300_ek` for a
 comprehensive sample.
 
 References

diff --git a/boards/shields/npm6001_ek/doc/index.rst b/boards/shields/npm6001_ek/doc/index.rst
@@ -28,7 +28,7 @@ Usage
 *****
 
 The shield can be used in any application by setting ``--shield npm6001_ek``
-when invoking ``west build``. You can check :ref:`npm6001_ek_sample` for a
+when invoking ``west build``. You can check :zephyr:code-sample:`npm6001_ek` for a
 comprehensive sample.
 
 References

diff --git a/boards/snps/hsdk/doc/index.rst b/boards/snps/hsdk/doc/index.rst
@@ -387,9 +387,9 @@ Set up Zephyr Software
 Building Sample Applications
 ==============================
 
-You can try many of the :ref:`sample applications and demos
-<samples-and-demos>`.  We'll use :zephyr:code-sample:`hello_world`, found in
-:zephyr_file:`samples/hello_world` as an example.
+You can try many of the :zephyr:code-sample-category:`sample applications and demos <samples>`.
+We'll use :zephyr:code-sample:`hello_world`, found in :zephyr_file:`samples/hello_world` as an
+example.
 
 Configuring
 -----------

diff --git a/boards/snps/hsdk4xd/doc/index.rst b/boards/snps/hsdk4xd/doc/index.rst
@@ -384,9 +384,8 @@ Set up Zephyr Software
 Building Sample Applications
 ==============================
 
-You can try many of the :ref:`sample applications and demos
-<samples-and-demos>`.  We'll use :zephyr:code-sample:`hello_world`, found in
-:zephyr_file:`samples/hello_world` as an example.
+You can try many of the :zephyr:code-sample-category:`sample applications and demos <samples>`.
+We'll use :zephyr:code-sample:`hello_world`, found in :zephyr_file:`samples/hello_world` as an example.
 
 Configuring
 -----------

diff --git a/boards/waveshare/esp32s3_touch_lcd_1_28/doc/index.rst b/boards/waveshare/esp32s3_touch_lcd_1_28/doc/index.rst
@@ -52,7 +52,7 @@ Asymmetric Multiprocessing (AMP)
 
 ESP32-S3 allows 2 different applications to be executed in ESP32-S3 SoC. Due to its dual-core
 architecture, each core can be enabled to execute customized tasks in stand-alone mode
-and/or exchanging data over OpenAMP framework. See :ref:`ipc_samples` folder as code reference.
+and/or exchanging data over OpenAMP framework. See :zephyr:code-sample-category:`ipc` folder as code reference.
 
 For more information, check the datasheet at `ESP32-S3 Datasheet`_ or the technical reference
 manual at `ESP32-S3 Technical Reference Manual`_.

diff --git a/doc/connectivity/bluetooth/bluetooth-arch.rst b/doc/connectivity/bluetooth/bluetooth-arch.rst
@@ -197,7 +197,7 @@ The stack is split up as follows in the source tree:
   have their own drivers.
 
 ``samples/bluetooth/``
-  :ref:`Sample Bluetooth code <bluetooth-samples>`. This is a good reference to
+  :zephyr:code-sample-category:`Sample Bluetooth code <bluetooth>`. This is a good reference to
   get started with Bluetooth application development.
 
 ``tests/bluetooth/``

diff --git a/doc/connectivity/bluetooth/bluetooth-dev.rst b/doc/connectivity/bluetooth/bluetooth-dev.rst
@@ -189,7 +189,7 @@ and scan response data.
 More Examples
 *************
 
-More :ref:`sample Bluetooth applications <bluetooth-samples>` are available in
+More :zephyr:code-sample-category:`sample Bluetooth applications <bluetooth>` are available in
 ``samples/bluetooth/``.
 
 .. _BabbleSim: https://babblesim.github.io/
diff --git a/doc/connectivity/usb/device/usb_device.rst b/doc/connectivity/usb/device/usb_device.rst
@@ -565,7 +565,7 @@ The USB Vendor ID for the Zephyr project is ``0x2FE3``.
 This USB Vendor ID must not be used when a vendor
 integrates Zephyr USB device support into its own product.
 
-Each USB :ref:`sample<usb-samples>` has its own unique Product ID.
+Each USB :zephyr:code-sample-category:`sample<usb>` has its own unique Product ID.
 The USB maintainer, if one is assigned, or otherwise the Zephyr Technical
 Steering Committee, may allocate other USB Product IDs based on well-motivated
 and documented requests.

diff --git a/doc/connectivity/usb/pd/ucds.rst b/doc/connectivity/usb/pd/ucds.rst
@@ -17,7 +17,7 @@ It provides the following functionalities:
 Currently the device stack supports implementation of Sink only and Source only
 devices. Dual Role Power (DRP) devices are not yet supported.
 
-:ref:`List<usbc-samples>` of samples for different purposes.
+:zephyr:code-sample-category:`List<usbc>` of samples for different purposes.
 
 Implementing a Sink Type-C and Power Delivery USB-C device
 **********************************************************

diff --git a/doc/develop/application/index.rst b/doc/develop/application/index.rst
@@ -303,7 +303,7 @@ Creating an Application by Hand
 
 You can follow these steps to create a basic application directory from
 scratch. However, using the `example-application`_ repository or one of
-Zephyr's :ref:`samples-and-demos` as a starting point is likely to be easier.
+Zephyr's :zephyr:code-sample-category:`samples` as a starting point is likely to be easier.
 
 #. Create an application directory.
 
@@ -643,7 +643,7 @@ assignment:
 
    CONFIG_CPP=y
 
-Looking at :ref:`existing samples <samples-and-demos>` is a good way to get
+Looking at :zephyr:code-sample-category:`existing samples <samples>` is a good way to get
 started.
 
 See :ref:`setting_configuration_values` for detailed documentation on setting

diff --git a/doc/develop/beyond-GSG.rst b/doc/develop/beyond-GSG.rst
@@ -213,7 +213,7 @@ format. Other binary formats, disassembly, and map files may be present
 depending on your board.
 
 The other sample applications in the :zephyr_file:`samples` folder are
-documented in :ref:`samples-and-demos`.
+documented in :zephyr:code-sample-category:`samples`.
 
 .. note:: If you want to reuse an
    existing build directory for another board or application, you need to

diff --git a/doc/develop/getting_started/index.rst b/doc/develop/getting_started/index.rst
@@ -478,7 +478,7 @@ Next Steps
 
 Here are some next steps for exploring Zephyr:
 
-* Try other :ref:`samples-and-demos`
+* Try other :zephyr:code-sample-category:`samples`
 * Learn about :ref:`application` and the :ref:`west <west>` tool
 * Find out about west's :ref:`flashing and debugging <west-build-flash-debug>`
   features, or more about :ref:`flashing_and_debugging` in general

diff --git a/doc/releases/release-notes-1.7.rst b/doc/releases/release-notes-1.7.rst
@@ -147,7 +147,7 @@ Documentation
 * Site-wide glossary added.
 * Porting guides added.
 * Sample README files converted to documents included in the website.
-* Improved consistency of :ref:`boards` and :ref:`samples-and-demos`.
+* Improved consistency of :ref:`boards` and :zephyr:code-sample-category:`samples`.
 
 
 JIRA Related Items

diff --git a/doc/services/device_mgmt/ota.rst b/doc/services/device_mgmt/ota.rst
@@ -45,7 +45,7 @@ is downloaded and installed. MCUboot can be used to verify the signature before
 upgrading the firmware.
 
 There is a :zephyr:code-sample:`hawkbit-api` sample included in the
-Zephyr :ref:`mgmt-samples` section.
+Zephyr :zephyr:code-sample-category:`mgmt` section.
 
 UpdateHub
 =========
@@ -56,7 +56,7 @@ the binary is downloaded and installed. MCUboot can be used to verify the
 signature before upgrading the firmware.
 
 There is an :zephyr:code-sample:`updatehub-fota` sample included in the Zephyr
-:ref:`mgmt-samples` section.
+:zephyr:code-sample-category:`mgmt` section.
 
 SMP Server
 ==========
@@ -66,8 +66,8 @@ Bluetooth Low Energy (BLE) or UDP. :ref:`mcu_mgr` is used to send a signed
 firmware binary to the remote device where it is verified by MCUboot before the
 upgrade occurs.
 
-There is an :zephyr:code-sample:`smp-svr` sample included in the Zephyr :ref:`mgmt-samples`
-section.
+There is an :zephyr:code-sample:`smp-svr` sample included in the Zephyr
+:zephyr:code-sample-category:`mgmt` section.
 
 Lightweight M2M (LWM2M)
 =======================

diff --git a/doc/services/portability/posix/overview/index.rst b/doc/services/portability/posix/overview/index.rst
@@ -113,7 +113,8 @@ leverages the ``nanosleep()`` and ``perror()`` POSIX functions.
         return 0;
     }
 
-For more examples of POSIX applications, please see the :ref:`POSIX sample applications<posix-samples>`.
+For more examples of POSIX applications, please see the
+:zephyr:code-sample-category:`POSIX sample applications<posix>`.
 
 .. _posix_config:
 

diff --git a/samples/application_development/application_development.rst b/samples/application_development/application_development.rst
@@ -1,16 +1,11 @@
-.. _application-development-samples:
+.. zephyr:code-sample-category:: application_development
+   :name: Application Development
+   :show-listing:
 
-Application development samples
-###############################
+   These samples illustrate some useful application development patterns and techniques.
 
 For application development you should also consider looking at
 `example-application`_. Among others, you will find on it out of tree driver
 or board examples.
 
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   **/*
-
 .. _example-application: https://github.com/zephyrproject-rtos/example-application
diff --git a/samples/arch/index.rst b/samples/arch/index.rst
@@ -1,10 +1,5 @@
-.. _arch-samples:
+.. zephyr:code-sample-category:: arch
+   :name: Architecture-dependent Samples
+   :show-listing:
 
-Architecture Dependent Samples
-##############################
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-
-   */*
+   Samples that demonstrate some architecture-specific features.
diff --git a/samples/arch/mpu/index.rst b/samples/arch/mpu/index.rst
@@ -1,10 +1,6 @@
-.. _mmu_mpu-samples:
+.. zephyr:code-sample-category:: mmu_mpu
+   :name: MMU/MPU
+   :show-listing:
 
-MMU/MPU Samples
-###############
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   **/*
+   Samples that demonstrate the Memory Management Unit (MMU) and Memory Protection Unit (MPU)
+   features.
diff --git a/samples/arch/smp/index.rst b/samples/arch/smp/index.rst
@@ -1,10 +1,5 @@
-.. _smp-samples:
+.. zephyr:code-sample-category:: smp
+   :name: Symmetric Multiprocessing (SMP)
+   :show-listing:
 
-Various SMP Samples
-###################
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   **/*
+   Samples that demonstrate the use of :ref:`Symmetric Multiprocessing <smp_arch>`.
diff --git a/samples/basic/basic.rst b/samples/basic/basic.rst
@@ -1,10 +1,5 @@
-.. _basic-sample:
+.. zephyr:code-sample-category:: basic
+   :name: Basic
+   :show-listing:
 
-Basic Samples
-#############
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   **/*
+   These samples demonstrate basic functionality of the Zephyr kernel.