This may be only tangentially related to the quality of Diátaxis, but trying to print the front page of their website (https://diataxis.fr/) for reference, almost kills my Chrome instance, which tries to produce 34,240 pages. I hope printing a single page of Python documentation in Diátaxis will not pull tens of thousands of pages.
That’s due to a Chrome bug. See details in Printing on Chrome generates way too many pages · Issue #358 · pradyunsg/furo · GitHub.
I’m guessing the Diataxis documentation is built with an old version of Furo as its base or makes changes in its stylesheet that reintroduces the issue. Firefox should work just fine. 
1 Like
I have thought about this before. One problem is that not infrequently, an example would break the flow because you have to explain things in sufficient detail to have the example make sense. It might not break the flow for you the very first time you need the example, but then you have to scroll past it every single time thereafter.
It would improve this aspect of the documentation to be able to make use of the HTML5 summary-detail elements, but to do this properly would need support at the Sphinx and perhaps docutils levels. As far as I know, that support isn’t available, though you can simulate it in a theme as I’ve done here. With such support, examples would take up just one line by default when in an unexpanded state, and as much space as needed when actually expanded by someone who needs to refer to the example. Another approach would be to use HTML tooltips to show examples while hovering over an “example” icon or similar, but again that would need choosing a suitable browser-side tooltip framework, play nicely with third-party themes and other build targets (than HTML), etc.
1 Like
There’s a simpler workaround: see my answer on StackOverflow Sphinx, reStructuredText show/hide code snippets - Stack Overflow
From a docutils / Sphinx perspective we could add support[1], although it would be hard to fit into the conceptual model of an “abstract document”, as e.g. PDF, ePub, OpenDocument don’t have similar support to the best of my knowedge. I also don’t believe there’s precedent for a writer-specific directive.
A
For example a
.. collapsible::directive that only takes effect on HTML writers/builders, and is a no-op on others. ↩︎
Well, a number of those answers would work, as does the approach in my theme. But IMO these approaches are a bit too error-prone for widespread use.
Agreed, but it seems the cleanest way to provide a definite quality improvment for what is probably the largest community of documentation readers. Rather than being a no-op on non-HTML platforms, it could be configured while building to either show nothing or the full expanded content.
The unittest docs include a basic example near the top, that explains the basic concepts in some details. At the very top of the page I added a shortcut that links to the assert methods, for people that are already familiar with the basic concept and just want to skip ahead to the reference. (Aside: the unittest docs might be a good candidate for a overhaul, and there have been several discussions about it in the past).
Note that depending on the the theme used, collapsed examples might be fairly easy to miss, especially while skimming through.
Anecdotally, I recently posted a short message on GitHub with two collapsed sections, and when I referred to them I had two people asking me what message I was talking about because they both didn’t notice/realize that in that message there were two collapsed sections. On GitHub (and by default in HTML5) the only hint is a small ⯈.
This doesn’t sound very usable if you want to select/copy/scroll, even though it might depend on the exact implementation of the tooltip.
1 Like
Yes, and I believe there are implementations where you can do all of scroll/select/copy.
Hiding examples in tooltips sounds undesirable to me, and I’d hope there would be a plain version without that.
1 Like
(@moderators, please could this thread be split from Adopting the Diátaxis framework for Python documentation - #43 by vsajip as the first post in the <details> conversation?)
A PR for Sphinx is up a Add support for collapsible content by AA-Turner · Pull Request #10532 · sphinx-doc/sphinx · GitHub – I’d appreciate if you could add a little detail on how you’d like the option to work in a comment on the PR, as I wasn’t too sure.
A
2 Likes
Well, this doesn’t need to be done in docutils or Sphinx natively – there’s a Sphinx extension written by one of the Sphinx maintainers for this:
4 Likes
I’ve commented on the PR, but in order to use this it would have to wait for the next Sphinx release, right, even if/when merged? And for Python’s documentation build to use that.
There’s also the much more popular and mature Sphinx-Design plugin by Executable Books, further-improved successor to the equally popular Sphinx-Panels. Its dropdown directive creates beautifully-styled <details> elements that are way more obvious than the default. It fully integrates with Furo as a major design goal (and I’d assuming Lutra too); you can see an example (with some extra styling and JS functionality) on our FAQ page.
3 Likes