Groups in the documentation home page table of contents are not exposed to assistive technology

[Natalia Bidart]

The groups on the home page table of contents exist only visually. The label is bold text and the links that follow it are separated by literal | characters, so nothing conveys to assistive technology that they belong together:

* **Getting started**:
  :doc:`/intro/overview` |
  :doc:`Installation </intro/install>`

As discussed in ​the forum, we should produce content that semantically reflects the proper hierarchy, independently of how we style it. Nested lists do that, with no extension and no new dependency:

* **Getting started**

  * :doc:`/intro/overview`
  * :doc:`Installation </intro/install>`

A screen reader then announces "Getting started, list with 2 items" before reading them.

One side effect worth mentioning is that the docs home page has 159 links in 39 groups, so one per line would lose the compact map. Keeping it needs a small rule in docs/_static/ (display: inline plus a generated separator), with a companion change on djangoproject.com, which has its own stylesheet.

Related to #37409 and #37051.

[Mike Edmunds]

Replying to Natalia Bidart:

[...] Keeping [the compact horizontal lists] needs a small rule in docs/_static/ (display: inline plus a generated separator), with a companion change on djangoproject.com, which has its own stylesheet. [...]

Another advantage of this change is it could help prevent screen readers from announcing the | separator characters as "pipe". (I think most skip that character by default, but I'm not certain. Fwiw, the ¶'s by every heading do get announced as "pilcrow" in VoiceOver.)

The stylesheet will need to render the visual separators in a way that is invisible to screen readers, such as border-inline-end or the new CSS ​content alt text (content: " | " / "";, supported in all major browsers since mid-2024).

Sphinx has an ​hlist directive that creates compact lists, but it seems to generate multi-column vertical lists (with a fixed number of columns) rather than the horizontal-style lists in Django's overview page. We could investigate using .. hlist:: with a :class: option for our custom html styling, which might also render better output in other formats like PDF. (Even with regular vertical lists, I think we'll need :class: or .. rst-class::` somewhere in the source to enable our custom CSS.)