I’ve set up a few one-off previews of the docs with and without toc_object_entries, and with a manual change to headings, to make it easier to compare the options:
main docs |
main RTD |
toc_object_entries |
Add headings |
|---|---|---|---|
| SchemaEditor | SchemaEditor | SchemaEditor | (skipped) |
| Paginator | Paginator | Paginator | (skipped) |
| File storage API | File storage API | File storage API | (skipped) |
| Models | Models | Models | Models |
Reviewing those examples, it seems pretty clear toc_object_entries is a win, with the caveats already mentioned that sometimes there’s been headings manually added, and the auto-generated TOC entry label is very verbose. However, for screen reader users it’s much better if there are actual headings in the content.
With actual headings, they’d be able to:
- Use screen reader support to navigate the page by headings, which is the most common form of navigation as reported by screen reader users.
- More consistently know when a given sub-section starts and how deep they are.
I’m fuzzy on the details but my understanding is most/all of Sphinx’s directives that rely on indentation will output description lists markup (dl with dt and dd), with the description term enhanced to act as a heading (heading styles, anchor link, and now TOC entries). While some usage of description lists is fine, I think it becomes problematic when they get used for overall page sections. They behave like headings for sighted users but come up short for screen reader users.
The issue is pretty clear for example in the Sphinx docs, in The Python Domain. About two thirds of that page’s content have no actual heading elements. For screen reader users the page is reported as having 5 headings, despite there being 67 entries in the table of contents. Those two numbers should probably match in an ideal world.
What to do
My recommendation for Django docs (and any other Sphinx project using those directives):
- See if it’s possible for those directives to create heading levels. If so, check whether it’d be best to do that and description lists markup, or just headings.
- Assuming that’s not possible / in the meantime, switch to manually creating headings instead with vanilla reStructuredText.
- If that’s not possible either / in the meantime,
toc_object_entries. It’s a good improvement but doesn’t solve the screen reader heading navigation problem.
Would love to do that whenever there’s a chance. I’ve not had much luck finding accessibility considerations / discussions in their project before, but can also be due to my lack of familiarity with it. I’m never too sure as far as markup what comes from docutils vs. Sphinx.