samples: bluetooth: use zephyr:code-sample directive #77760

kartben · 2024-08-29T17:27:08Z

Describe the Bluetooth samples using code-sample directive in preparation for upcoming changes to the Zephyr documentation that will be leveraging the provided description and metadata.

This is a work in progress but I am almost done. Perhaps the main "disruptive" change this is introducing is dropping "Bluetooth: " prefix in front of all the samples' names, but hopefully people agree it is redundant :)

The "descriptions" are not prominently featured just yet but will be in an upcoming update to how samples are listed. It will look something like the below, which hopefully illustrates the added value of these short descriptions :)

Could people added as early reviewers confirm that this is going in the right direction for them and that I didn't miss something obvious or a constraint specific to Bluetooth samples?

Note that the upcoming change to the docs will allow to add code sample categories, so it might make sense to add new groups for TMAP, HCI, etc. at some point

jori-nordic · 2024-08-30T07:10:12Z

boards/vngiotlab/nrf51_vbluno51/doc/index.rst

- * :ref:`bluetooth-beacon-sample`
- * :ref:`peripheral_hr`
+ * :zephyr:code-sample:`bluetooth_beacon`
+ * :zephyr:code-sample:`ble_peripheral_hr`


why is one prefixed with bluetooth_ and the other with ble_? Don't think the beacon sample runs on a classic stack.
I would prefer bluetooth_classic_xx for classic samples, and the rest is assumed to be LE.
What do you think?

There's a few more with the same inconsistency. Also some that is prefixed with _, and even one that is bluetooth_bt :D

Are we planning on using explicit tags, or should we attempt to shorten them at bit? e.g.

bluetooth_beacon => bt_beacon bluetooth_direction_finding_central => bt_df_central

I would prefer long names for the documentation references. Shortening the filenames/path should be ok. Although i hope people have shell completion

The simplest route might be to just use the same IDs as the folder names?
Related: is it time to introduce some subfolders underneath samples/bluetooth? It's starting to get really packed in there :)

The simplest route might be to just use the same IDs as the folder names? Related: is it time to introduce some subfolders underneath samples/bluetooth? It's starting to get really packed in there :)

#64443 :)

The simplest route might be to just use the same IDs as the folder names? Related: is it time to introduce some subfolders underneath samples/bluetooth? It's starting to get really packed in there :)

Sure, so we can have bluetooth prefix for all BT samples, and then, when we do the above move, we can have them like bluetooth_audio_xxx, bluetooth_mesh_xxx

samples/bluetooth/central_hr/README.rst

jori-nordic · 2024-08-30T07:24:15Z

samples/bluetooth/hap_ha/README.rst


-Bluetooth: HAP Hearing Aid (HA)
-###############################
+   Advertise and XXX


Demonstrate the Bluetooth LE Audio Hearing Aid role

jori-nordic · 2024-08-30T07:24:59Z

samples/bluetooth/hci_ipc/README.rst


-Bluetooth: HCI IPC
-##################
+   Expose Zephyr Bluetooth controller to another device or CPU using the IPC subsystem.


It can be any configured bluetooth controller. eg, even one connected over UART

same comment for the other hci_xx samples

I took the wording from the "Overview" section of most HCI samples, so I guess they need to be fixed?
https://docs.zephyrproject.org/latest/samples/bluetooth/hci_spi/README.html#overview

oh yeah then they need to fixed, yes

should be addressed both in the new descriptions and legacy "Overview" sections

jori-nordic · 2024-08-30T07:26:18Z

samples/bluetooth/hci_usb_h4/README.rst


-Bluetooth: HCI H4 over USB
-##########################
+   Turn a Zephyr board into a USB H4 Bluetooth dongle.


Turn a Zephyr board into a USB H4 Bluetooth dongle. Only supported by BlueZ on linux.

jori-nordic · 2024-08-30T07:26:44Z

samples/bluetooth/hci_usb/README.rst


-Bluetooth: HCI USB
-##################
+   Turn a Zephyr board into a USB Bluetooth dongle.


Turn a Zephyr board into a USB Bluetooth dongle. Compatible with all major operating systems (Mac, Windows, Linux).

Not sure I agree with making the "short" description that long but I get your point and will see if I can add the precision in a maybe more concise way if you really think it's important to have it right at the sample listing level.

jori-nordic · 2024-08-30T07:29:45Z

samples/bluetooth/hci_vs_scan_req/README.rst


-Bluetooth: HCI VS Scan Request
-##############################
+   Manage vendor-specific HCI commands to obtain scan request events even using xxx.


Use vendor-specific HCI commands to enable Scan Request events when using legacy advertising.

Thalley · 2024-08-30T16:02:07Z

boards/vngiotlab/nrf51_vbluno51/doc/index.rst

- * :ref:`bluetooth-beacon-sample`
- * :ref:`peripheral_hr`
+ * :zephyr:code-sample:`bluetooth_beacon`
+ * :zephyr:code-sample:`ble_peripheral_hr`


The simplest route might be to just use the same IDs as the folder names? Related: is it time to introduce some subfolders underneath samples/bluetooth? It's starting to get really packed in there :)

Sure, so we can have bluetooth prefix for all BT samples, and then, when we do the above move, we can have them like bluetooth_audio_xxx, bluetooth_mesh_xxx

Thalley · 2024-08-30T16:04:48Z

samples/bluetooth/bap_broadcast_sink/README.rst

+   :name: Broadcast Audio Sink
   :relevant-api: bluetooth

-   Bluetooth: Broadcast Audio Sink
+   Use LE Audio Broadcast Sink functionality.


I think I'll follow up with a name update PR later - I think several of our LE audio samples could benefit from better names and descriptions, but let's not muddy this PR too much with that :)

Yes, this would be awesome. It's true that a lot of the names and descriptions are very "content-free" right now and not all that helpful. Hopefully the follow-up PR will be much easier to implement once the directives will already be there :)

samples/bluetooth/bthome_sensor_template/README.rst

Thalley · 2024-08-30T16:07:04Z

samples/bluetooth/cap_acceptor/README.rst

@@ -1,8 +1,8 @@
 .. zephyr:code-sample:: bluetooth_cap_acceptor
-   :name: Bluetooth: Common Audio Profile Acceptor
+   :name: Common Audio Profile Acceptor


What do you prefer:

Common Audio Profile Acceptor

Common Audio Profile (CAP) Acceptor

CAP Acceptor

Just in case we want to be consistent with the Audio samples later

is probably best as this makes it easier to capture all the various types/combination of search queries users might perform

I thought someone said they would address naming in a follow-up PR though? :P

samples/bluetooth/central_iso/README.rst

samples/bluetooth/ibeacon/README.rst

samples/bluetooth/periodic_adv/README.rst

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]>

Replace occurrences of "BLE" by the recommended "Bluetooth LE" term. Signed-off-by: Benjamin Cabé <[email protected]>

Thalley · 2024-09-02T08:06:29Z

samples/bluetooth/central_gatt_write/README.rst

@@ -1,19 +1,20 @@
-.. _bluetooth_central_gatt_write:
+.. zephyr:code-sample:: ble_central_gatt_write


Similar to the BLE -> Bluetooth LE change you did, we should probably do it for the references as well - Especially the ones that you've added/modified in this PR

Suggested change

.. zephyr:code-sample:: ble_central_gatt_write

.. zephyr:code-sample:: bluetooth_central_gatt_write

They can also match the prefix we use in the stack as a shorter alternative:

Suggested change

.. zephyr:code-sample:: ble_central_gatt_write

.. zephyr:code-sample:: bt_le_central_gatt_write

Sure, I can give it a try.

I am actually not sure I have the knowledge required to pick the "right" prefix. I would frankly just name them bt_<samplefoldername>. The point is really just to have some kind of unique ID for documentation purposes, it's not like it's directly exposed to the end user or anything

it's not like it's directly exposed to the end user or anything

Nor do we have any documentation or guidelines for naming schemes of sample labels :)

Doesn't need a fix in this PR, but arguably something that makes sense to make consistent later

Thalley · 2024-09-02T08:08:22Z

samples/bluetooth/direction_finding_central/README.rst

-.. _bluetooth_direction_finding_central:
+.. zephyr:code-sample:: bluetooth_direction_finding_central
+   :name: Direction Finding Central
+   :relevant-api: bluetooth


What was your process for finding the relevant APIs?

I think any central sample should also have bt_conn as a API reference, as that is used to establish the connections

My process can be best described as "best effort" for an initial pass :)

Alright - Thought you might have made a script to check which functions were called (which in theory is possible, although not a 5-min task ;) )

kartben · 2024-09-05T16:58:57Z

@jhedberg @jori-nordic good enough for you guys? Happy to address some remaining tweaks that would be needed but ideally we can continue any pending housekeeping tasks in follow-up PRs. Thanks!

kartben force-pushed the bt_samples_doc branch 7 times, most recently from 71c8db2 to d8032cd Compare August 30, 2024 06:38

kartben requested review from jhedberg, Thalley and jori-nordic August 30, 2024 06:50

jori-nordic reviewed Aug 30, 2024

View reviewed changes

samples/bluetooth/central_hr/README.rst Outdated Show resolved Hide resolved

jori-nordic reviewed Aug 30, 2024

View reviewed changes

jhedberg self-assigned this Aug 30, 2024

kartben force-pushed the bt_samples_doc branch 4 times, most recently from 8a08d7e to 4a0fffa Compare August 30, 2024 15:18

Thalley reviewed Aug 30, 2024

View reviewed changes

kartben added 2 commits September 2, 2024 09:27

samples: bluetooth: use zephyr:code-sample directive

28808f3

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]>

samples: bluetooth: Use "Bluetooth LE" terminology

6d1af38

Replace occurrences of "BLE" by the recommended "Bluetooth LE" term. Signed-off-by: Benjamin Cabé <[email protected]>

kartben force-pushed the bt_samples_doc branch from 4a0fffa to 6d1af38 Compare September 2, 2024 07:27

kartben marked this pull request as ready for review September 2, 2024 07:30

zephyrbot requested review from alwa-nordic, asbjornsabo and Casper-Bonde-Bose September 2, 2024 07:31

zephyrbot requested review from fredrikdanebjer, hermabe, kruithofa, larsgk, MariuszSkamra, nashif, sjanc and theob-pro September 2, 2024 07:31

Thalley reviewed Sep 2, 2024

View reviewed changes

Thalley approved these changes Sep 5, 2024

View reviewed changes

jhedberg approved these changes Sep 5, 2024

View reviewed changes

nashif merged commit d1858d2 into zephyrproject-rtos:main Sep 5, 2024
20 checks passed

kartben deleted the bt_samples_doc branch September 10, 2024 19:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

samples: bluetooth: use zephyr:code-sample directive #77760

samples: bluetooth: use zephyr:code-sample directive #77760

kartben commented Aug 29, 2024 •

edited

Loading

jori-nordic Aug 30, 2024

Thalley Aug 30, 2024

jori-nordic Aug 30, 2024

kartben Aug 30, 2024

Thalley Aug 30, 2024

Thalley Aug 30, 2024

jori-nordic Aug 30, 2024

jori-nordic Aug 30, 2024

jori-nordic Aug 30, 2024

kartben Aug 30, 2024

jori-nordic Aug 30, 2024

kartben Aug 30, 2024

jori-nordic Aug 30, 2024

jori-nordic Aug 30, 2024

kartben Aug 30, 2024

jori-nordic Aug 30, 2024

Thalley Aug 30, 2024

Thalley Aug 30, 2024

kartben Aug 30, 2024

Thalley Sep 6, 2024

Thalley Aug 30, 2024

kartben Sep 5, 2024

Thalley Sep 2, 2024

Thalley Sep 2, 2024

kartben Sep 3, 2024

kartben Sep 5, 2024 •

edited

Loading

Thalley Sep 5, 2024

Thalley Sep 2, 2024

kartben Sep 3, 2024

Thalley Sep 4, 2024

kartben commented Sep 5, 2024

		@@ -1,19 +1,20 @@
		.. _bluetooth_central_gatt_write:
		.. zephyr:code-sample:: ble_central_gatt_write

	.. zephyr:code-sample:: ble_central_gatt_write
	.. zephyr:code-sample:: bluetooth_central_gatt_write

	.. zephyr:code-sample:: ble_central_gatt_write
	.. zephyr:code-sample:: bt_le_central_gatt_write

samples: bluetooth: use zephyr:code-sample directive #77760

samples: bluetooth: use zephyr:code-sample directive #77760

Conversation

kartben commented Aug 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kartben Sep 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kartben commented Sep 5, 2024

kartben commented Aug 29, 2024 •

edited

Loading

kartben Sep 5, 2024 •

edited

Loading