Can use with other tab libraries

[AWhetter]

Since creating the original issue I've stopped using sphinx-tabs and moved onto using sphinx-design. To remove the reliance on any one tab library, I've opted to add a :http:example-block: directive for translating and rendering a HTTP request or response anywhere, including in tab directives from other Sphinx extensions.

Closes #25

If you would like me to make httpexample use sphinx-tabs in addition to this change, I've got a working example of that (https://github.com/AWhetter/sphinxcontrib-httpexample/commit/8769655eb1d7f4367fc60fdc07324be20a876539) but I'll need to change it to work with this new directive.

[stevepiercy]

Is this compatible with, or a replacement for, https://github.com/collective/sphinxcontrib-httpexample/pull/94?

I use sphinx-design in almost all my documentation projects, and I think consistent design would be a nice touch.

[AWhetter]

This is indeed compatible with #94. The usage of other tab libraries is done independently of the automatic generation of a tabs by httpexample.

[datakurre]

@stevepiercy @AWhetter Thank you! This is interesting.

Is sphinx-design + sphinx-inline-tabs the same as this https://sphinx-inline-tabs.readthedocs.io/en/latest/

It does not look accessible (no aria-attributes or keyboard navigation support).

But sphinx-tabs looks accessible https://sphinx-tabs.readthedocs.io/en/latest/

Maybe I am missing something here?

So, sphinx-tabs is not compatible with sphinx-design? I am sorry for not being very up-to-date with the current Sphinx extension trends. Dropping custom tabbing would be nice, but I'd like to do it without requiring source syntax change (by using the chosen tabbing directives implicitly).

In any case, I should probably first release a version without jQuery requirement and then look into this.

Sorry about the test setup. The test failure are probably just missing deps in https://github.com/collective/sphinxcontrib-httpexample/tree/master/nix where I have collection of Poetry lock files for deterministic tests on Python 3 and a custom thing for Python 2.7.

[stevepiercy]

@datakurre there are numerous tab projects, and they're all intertwingled. Various Sphinx theme and extension authors have collaborated over the last 3 years to improve accessibility, usability, and features. executablebooks and pradyunsg are two key developers.

• https://pypi.org/project/sphinx_design/
• https://pypi.org/project/sphinx-tabs/
• https://pypi.org/project/sphinx-inline-tabs/

sphinx-design (SD) is the most widely used tab package of these three (https://pypistats.org/packages/sphinx-design), and is used in the following major Sphinx themes:

• alabaster
• sphinx-book-theme
• pydata-sphinx-theme (PST)
• sphinx-rtd-theme
• furo

You can check out the tab demos in each of those themes.

---

As far as accessibility, I looked at demos of both:

• https://sphinx-design.readthedocs.io/en/latest/tabs.html#tabbed-code-examples
• https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/web-components.html#tabs

They are both accessible. They both use <input type="radio"> to activate each tab. The difference is that there is a lack of CSS in SD to indicate that you have tabbed onto the radio button, whereas PST has styling. In SD, try tabbing around until it seems that nothing got selected, then use the right and left arrow keys.

[datakurre]

As far as accessibility, I looked at demos of both:

* https://sphinx-design.readthedocs.io/en/latest/tabs.html#tabbed-code-examples
* https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/web-components.html#tabs

When I look them, both are missing aria-attributes and the first one does not have any default styles to indicate that keyboard focus is within tab list.

I'd guess something implementing this would be ideal: https://www.w3.org/WAI/ARIA/apg/patterns/tabs/examples/tabs-automatic/

What would you recommend? Should I keep the custom tabbing (and maybe review and enhance its accessibility too)? Should I only support tabbing provided by some specific themes / add-ons? Should I try to sniff the available add-on or should there be configuration options for this?

Of course, perfect is the enemy of good. Automatic support sphinx-design tabs maybe? And keep custom tabbing implementation when sphinx-design is not available (or would configuration option be the only safe option?).

[datakurre]

Or maybe the way this pull is implemented after all? Keep the current behavior for existing uses, but provide the new directive for sphinx-design-tabbing.

@stevepiercy How would you like the proposed support in this pull, where you need to define every tab in source?

[stevepiercy]

@datakurre if I understand this PR correctly, it adds support for reStructuredText or MyST markup for sphinx-design and sphinx-inline-tabs, while keeping the current implementation.

I prefer the less verbose markup and the aria attributes that the current implementation of sphinxcontrib-httpexample provides, even though they are injected by JavaScript. I prefer the design of and lack of JavaScript in sphinx-design.

In a perfect world, either a theme or extension would insert appropriate aria attributes using Python and without JavaScript. If that is done in sphinxcontrib-httpexample, it would be portable to other themes.

I could open an issue to start a conversation with the SD maintainers to see if they are interested in including aria attributes in the tabs. I don't think it is on their radar, but if we bring it up, then I bet they would like to add it. It would make all the other theme authors who care about a11y very happy.

As far as details, which attributes would you like to see? I see that sphinxcontrib-httpexample uses these attributes with example values, which SD lacks.

role="tab"
tabindex="0"
aria-label="http"
aria-controls="id1"
aria-selected="true"

[datakurre]

I didn't know that sphinx-design had implemented tabs without JavaScript. That's almost too clever markup + css. I'm not sure if dynamic aria-attributes are achievable that way, though.

I guess, simply merging and releasing this pull is the best compromise for now.

I am also sorry for still not wanting to drop Python 2.7 support, so I'll do some refactoring to make the docs build when the those new tab extensions are not available.

Thanks!

[stevepiercy]

You're correct, only JavaScript can change the ARIA attributes in the DOM. I actually did not realize that sphinxcontrib-httpexample changed them, but now I see why it is necessary. I take back my preference against modifying them via JavaScript in this use case.

I started an "idea" discussion with the SD folks about adding ARIA attributes. I'm curious why they don't include them, but perhaps the requirement of JavaScript to have dynamic ARIA attributes is the reason. Maybe they'll adapt this JavaScript. 😁

[stevepiercy]

I agree that merging this PR would be a good compromise.