There’s an accessibility problem. You can see it most easily if you do a search for “Overview”: it appears 19 times, 18 of which are links.
A visual user can see that one is an overview of model fields, another of testing, and so on, but the user of a screen readers doesn’t get the context that would allow them to understand that without additional effort.
The solution would be to provide ARIA attributes on ambiguous links.
As well as handling ARIA attributes when they are required, it can provide ambiguity warnings
It also marks up the table of contents as navigation, and as a clean nested <ul>. It uses CSS (instead of characters in the HTML) to provide the separators between links.
I’m applying it to the Django documentation; you’d have to look twice to know that there is anything different:
I hope we can use it for Django. We’d need various things to get there: to test it thoroughly; probably extend it a little to accommodate some of the patterns on the home page right now; check with an expert whether it really does do all the correct things; test with users to find out what the best practices for our home page would be.
I’m generally positive on this idea. The extension’s home page gives a nice overview of the problem and solution: sphinx-structured-toc.
The more our docs sources can reflect the structure of the content—and leave the formatting and presentation to the Sphinx tooling—the better (imho). And then the tooling needs to generate the best representation possible for that structure in each output format—including using all appropriate accessibility features. Creating a structured toc seems like a step in that direction. (Also, the presentational | characters in docs/index.txt have bugged me for a while now.)
A few concerns with sphinx-structured-toc:
The big one you point out: check with an expert on whether the resulting html solves a problem in the existing accessibility tree. I’m a little suspicious of so many nav elements, but I’m not a screen reader user. Is there any relevant guidance from WAI-ARIA or others on long tables of contents? (My quick search didn’t find any.)
Can it support all output formats that Django generates? (ePub, manpage, etc.)
It’s a new dependency. It would be docs build-time only, but all dependencies come with maintenance, longevity, and supply-chain concerns. (I think a well-maintained dependency is a reasonable trade-off against trying to handle something like this ourselves. For similar reasons we’re looking at replacing the custom, largely unmaintained docs/_theme/djangodocs Sphinx theme with a third-party package.)
I’m guessing the GPL license might be an issue, both because the extension places content (a css file at least) into Django’s built docs and because that license would preclude vendoring the extension into Django if it were ever necessary. (But I’m not really the right person to ask.)
I also have several smaller questions/comments about things like directive names (confusion vs. Sphinx’s “domains”?), input format (should it look like an hlist?), and generated html (could it reference existing, visible nodes to avoid adding visually-hidden elements?). But those are details, and might be better handled in the extension’s repo.
Overall, though. sphinx-structured-toc seems like a good idea to me.
(Also, btw, thanks for your updates to the docs home page. It’s a huge improvement!)
Regarding best practices, including the nav elements: the extension needs to follow those, so if it doesn’t that will be a priority to address. We’re starting to use it at reasonable scale at Canonical so I am hoping to get a lot of real-world feedback from users as well as expert advice on implementation details.
I’d like to find ways of ensuring that it becomes and stays an attractive option for third-party use, so will take any advice on licensing-related questions.
Thanks Daniele, and thanks Mike for the detailed look. I would like to separate two things:
the accessibility problem, which is real and affecting users today, and
the tool, which needs more testing and development before we could adopt it.
I do not think we have to wait for the second to fix the first, so I have created a ticket for that. I think a good part of this is self-inflicted and fixable in docs/index.txt alone. Of the many Overview links, every single target document already has a distinct, self-describing title. For most of them the fix is to delete the explicit title and let :doc: use the document’s own. I have a branch doing that, plus some regrouping, and the page now has no duplicated link text at all. I will open it as a PR shortly so we can talk about something concrete.
On sphinx-structured-toc itself, in addition to Mike’s points about licensing, output formats, and taking on a new dependency, a few things I ran into:
It pins sphinx~=7.0. We build the docs on Sphinx 9.1, so it cannot currently be installed alongside.
It ships a CSS file into the built output via add_css_file(), so the GPL question is not hypothetical: a GPL-3.0 file would end up in docs the DSF distributes. That one is probably a board question rather than ours.
It registers app.add_node(nodes.reference, html=(...), override=True), so every link in the docs goes through its visitor, which then patches the generated HTML as text, after the fact.
That last point is the one I keep coming back to. We are currently removing exactly that pattern from docs/_ext/djangodocs.py under ticket #37212, because overriding the HTML writer breaks across Sphinx versions and blocks moving to a maintained third-party theme (ticket #37138). Taking on a dependency that does the same thing, at an arguably wider blast radius, would work against the direction we are working hard to go.
None of which is an argument against the tool maturing into something we use later. But I do think we should aim at fixing what we can fix now in our own sources, and revisiting once the licensing and Sphinx support questions have answers.
