"Devices" Information Descriptors format

[PetroBondar]

We faced some problems with updating the Information Descriptors section for sycl::device. We have three options for how information can be formatted there:

1. In table like we did in "Platforms" and "Contexts":
   

   KHRGA-57_RC_devices branch

   Pros: Consistency, description added, easy-to-understand structure
   Cons: Some names are so long (even if you try to shrink them) that the table becomes enormously wide (still looking for a solution), so the contents will cover it partially. The page becomes very big.

2. Using subsections:
   

   KHRGA-57_RC_devices_no_table branch

   Pros: Description added, full names without removing scopes, easy-to-understand structure
   Cons: For consistency, updating "Platforms" and "Contexts" will be necessary. The page becomes very big

3. Leaving the link to the spec, like it was previously:
   

   Pros: The page will become more concise
   Cons: No description will be added for "Information Descriptors"

Which option is better? Or are there any other proposals?

[mkinsner]

I prefer the table format (option 1), but I agree that the navigation bar on the right overlapping with the table contents isn't great. I think we should continue with option 1, and can adjust later if needed. The navigation bar only covers the top rows of text so the table is still very usable.

Option 2 makes the navigation bar too long with all the subsections and is generally too long in content, and option 3 doesn't provide enough information.

[PetroBondar]

Ok, I think, we'll proceed with option 1 for now.

Should we in this case provide full names (starting with sycl:: namespace)? It'll make the table a bit wider, but we'll сomply with the issue #72

[mkinsner]

Yes, I think we should include sycl:: on the descriptor names for consistency. We can consider other options in the future once we have experience with this format.

[gmlueck]

Couldn't we have something like option 2, but without making subsections? This would avoid super wide tables, and it would avoid the long navigation bar that @mkinsner is concerned about.

[mkinsner]

Couldn't we have something like option 2, but without making subsections? This would avoid super wide tables, and it would avoid the long navigation bar that @mkinsner is concerned about.

I think that would be fine as well. Can we avoid the subsection navigation bar issues easily?

[rscohn2]

I think that would be fine as well. Can we avoid the subsection navigation bar issues easily?

A rubric might do it.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-rubric

[PetroBondar]

I tried different approaches and, as I understood, using a rubric is the best one for now...

In code it will look somehow like this:

.. rubric:: ``sycl::info::device::device_type``

Returns the device type associated with the device.
May not return ``sycl::info::device_type::all``.

+--------------------------------------+
| Return type: :ref:`info-device_type` |
+--------------------------------------+


.. rubric:: ``sycl::info::device::vendor_id``

Returns a unique vendor device identifier.

+---------------------------+
| Return type: ``uint32_t`` |
+---------------------------+

Another option was to modify the content box to ignore lower-level sub-titles and use them (it will look better, I believe, but I didn't figure out how to modify contents on this page)

[gmlueck]

I like the way this looks in the rendered HTML, and I prefer it to either of the previous options.

Another option was to modify the content box to ignore lower-level sub-titles and use them (it will look better, I believe, but I didn't figure out how to modify contents on this page)

This could be good too. I suppose it has the advantage that each info descriptor would have it's own URL, so you could easily point someone to a specific descriptor (e.g. in an email conversation).

[PetroBondar]

If everyone is okay with how it looks, we can make it this way.

Meanwhile, I'll try to investigate if there is a way to ignore sub-titles in Contents.