doc: samples: Introduce code sample categories

[kartben]

https://builds.zephyrproject.io/zephyr/pr/77400/docs/samples/index.html

This PR enhances the documentation framework by introducing support for categorizing and listing code samples. This also makes better use of the already available metadata that .. zephyr:code-sample directive allows to associate to each sample, namely, the short description.

New directives:

.. zephyr:code-sample-category:: Defines a category for grouping related code samples, which is similar to what used to be manually done, and usually in an inconsistent way. Also for the sake of consistency and minimizing the risk of people misusing Sphinx's toctree, the directive also acts as an implicit toctree, "mounting" all the samples (or sub-categories) underneath it.

.. zephyr:code-sample-listing:: Generates a listing of all the samples for a category (or more than one, actually), optionally with an input field allowing to do filtering of the samples and get them "MQTT", "PWM", "ESP32", etc. samples to quickly show up.

New roles:

• :zephyr:code-sample-category:: References a code sample category from anywhere in the documentation, similar to :zephyr:code-sample: role.

This change should also help encourage code sample authors to take better care of the metadata (ex. have a really good short description) for their samples as this makes them much more discoverable.

Limitations:

• Sub-categories and code samples are always listed alphabetically. If deemed useful, I can add some kind of "featured-subcategories" and "featured-samples" options to allow "promoting" some items to the top of their respective lists, but I am not certain this is critical to have (in this first implementation, or ever). It's true that we may want the "Basic" category to be listed first, though, so definitely open to discussion especially as I have some working code for this already (just don't feel like making the directive crazy-customizable from day 1 if not strictly needed).

  Sorting everything alphabetically is arguably infinitely better and more consistent than what we had anyway, as samples in a given category would typically be listed according to their folder name, which might be very different from their actual name as per the title of the README. Therefore, listing such as https://docs.zephyrproject.org/latest/samples/bluetooth/bluetooth.html or https://docs.zephyrproject.org/latest/samples/net/net.html are effectively very randomly sorted today and not very easy to navigate at a glance.

• Incremental build might need some polishing, but it's likely also true for code-samples, as some dependencies might not alway be captured.

• Not necessarily a limitation as this forces us to also organize documentation sources cleanly in the first place but atm it's not possible to define categories in just any document and then randomly "attach" a sample to a given category. A category needs to be defined in a folder that contains a sample, and a sample is automatically added to the first category found in its parent folders' hierarchy.

  What that means in practice is should e.g. Bluetooth want to create sub-categories for e.g. Mesh, Audio, etc., the first step would be to create samples/bluetooth/audio/, samples/bluetooth/mesh, etc., move the relevant samples there, and then add an .rst file declaring the category in said folders. Again, not necessarily a limitation IMO, just something to be aware of.

Includes a commit from #77478 as I wanted to already align the docs for the new directives/roles with the changes implemented there.

The actual Sphinx extension work is in the commit doc: extensions: samples: Introduce code sample categories and the changes in the commit that follows, while intimidating, are really about converting existing "legacy" categories and references to them to the new system.

[Thalley]

Will review once #77478 has merged. Suggest to put DNM or something like that on the PR to prevent this from merging before #77478.

[kartben]

Adding a "DNM" as per @Thalley's suggestion and to reflect dependency on doc updates in #77478

[Thalley]

Suggested change

	See :zephyr:code-sample-category:`Bluetooth samples section <bluetooth>` for details.
	See :zephyr:code-sample-category:`bluetooth` samples for details.

Suggest to make this consistent with the others

[kartben]

Sure! As you can probably imagine, I went for the easy "search and replace" without necessarily putting more thought into it :)

[kartben]

@gmarull did you have time to take a look at this PR? I might not be able to come back to it soon but as it will likely be a source of merge conflicts, it would be good to get this in sooner than later in case it is good enough to go. Thanks!

[carlescufi]

This is great stuff! Thanks @kartben