Figuring out our strategy for tabbed content

[pradyunsg]

Is your feature request related to a problem? Please describe.

Currently, sphinx-tabs and sphinx-panels both provide tabbed-content functionality. This overlap isn't super useful and creates a very weird dynamic. Right now, we have two implementations of the same fundamental thing living in 2 packages maintained by the same group of people.

• sphinx-tabs: currently outdated, is generally more capable than sphinx-panel's CSS-only implementation of tabs.
• sphinx-panels: A CSS-only package, providing (among other things) a tabbed directive that generates tabs adopted from mkdocs-material, looks great on the final page. :)

Describe the solution you'd like

We move the sphinx-panels implementation of tabs into sphinx-tabs and remove the tabbed directive from sphinx-panels. The sphinx-tabs implementation would be modernized, and, heck, we could even have the tabbed directive added to it directly.

Basically, I'm volunteering to rewrite sphinx-tabs to look nicer whilst also adding graceful degradation and solving executablebooks/sphinx-tabs#87 (and a few more) but I don't want to step on anyone's toes and I want to make sure we're all on the same page. :)

Open Questions

• What does Chris think about this idea? :P
• Directive design:
  • How important is it to preserve the current structure of sphinx-tabs's directives?
  • How important is it to preserve the current structure of the tabbed directive?
  • Should we include both or only one of them in the rewrite? If so, which one?

[chrisjsewell]

Well I'm not really that bothered about sphinx-tabs anymore, now that (simple) tabs are in sphinx-panels lol, so go ahead do your worst (although we should pay some attention to back compatibility for current users)
As to whether this should then prompt the removal of tabbed from sphinx-panels.
It really just depends on the final implementation. sphinx-panels is now included in jupyter-book and provided a nice "non-obtrusive" addition for general users, and obviously I named it different to the directives in sphinx-tabs so that both can still be used without issue.
I would be hesitant to include sphinx-tabs at least in its current form.

[choldgraf]

yeah I think it's worth emphasizing that last point - sphinx-tabs isn't bundled with Jupyter Book, and so I think that reduces the confusion a bit. I think of it as more of a "power user" tab tool that we can also expect users to be able to manually configure if they wish.

I do think that at some point if panels continues growing in complexity, we'll want to modularize it a bit, and perhaps this could be a part of that, but I don't think it's a big fire right now

@pradyunsg what are the main features that sphinx-tabs has that this implementation does not?

[pradyunsg]

@choldgraf Synchronized tabs, and... that's it? Yea. :)

[choldgraf]

I wonder if @chrisjsewell would be willing to just baaaaarely relax his "no JS" rule in this one use-case of synchronized tabs? :-)

[chrisjsewell]

I wonder if @chrisjsewell would be willing to just baaaaarely relax his "no JS" rule in this one use-case of synchronized tabs? :-)

I wouldn't hold your breath. First you would have to actually provide a PR for this solution, and also show that you have tried to implement it in a non-JS way first.
Even then I'm not guaranteeing that I would accept the PR. I have already explained the benefits of CSS only approaches over JS, and there are even other benefits that I hadn't considered (see executablebooks/sphinx-tabs#92). If you are going to break all that for a feature that no one on jupyter-book has actually asked for yet, then I would politely decline.

[chrisjsewell]

never say never though 😆

[choldgraf]

I am on board with @chrisjsewell 's general principle of no JS unless absolutely necesssary. I'm also not a fan of maintaining two libraries with 90% overlap in functionality (tabs in panels vs. sphinx-tabs), so really my main point is that I'd like to find a way for us to deprecate one of those two pieces :-) (probably sphinx-tabs?). If our concern about adding in JS in sphinx-panels is complexity and maintainability, then it seems like "maintaining an entire other tabs library just to also have the option to use JS" is a net-loss of our time. So I am generally happy with any decision here that results in a net-growth in our available time :-)

Maybe a step forward would be -

0. Decide whether we want to have "tabs in sphinx-panels" or if we want to bring "sphinx-panels tabs into sphinx-tabs"
1. Either way, deprecate this functionality in one of the two packages (if we keep it in sphinx-panels, we can just set sphinx-tabs as maintenance-only or something)
2. See if we can implement sync-ed tabs with CSS and HTML only
3. If not possible, see how complex it'd be to do this with JS. Only merge if it is maybe < 10 lines of JS or something.

Another approach could be that we just say "sphinx-panels will not support synchronized tabs" and then we need to decide if we want to keep maintaining a separate tabs library just for this functionality.

I guess for an implementation of "synchronized tabs in sphinx-panels", I'd imagine we'd introduce an extra key/value pair like id or link and then this would make its way into the DOM element for each tab so that when it was clicked, a callback could look for any elements with the same idea and simulate a click on them too. I'm not sure but if tabs had data-id elements we might be able to get by here with just CSS?

[pradyunsg]

From my perspective... the tabs implementation in sphinx-panels is basically independent of the rest of sphinx-panels. It doesn't depend on bootstrap, or on any other elements in sphinx-panels.

All the deficiencies of sphinx-tabs that are being flagged by @chrisjsewell are... trivial-ish to fix IMO. I view them as a consequence of the status-quo implementation there not being great/not considering those needs and not a case of CSS-only vs JS+CSS. A rewrite of sphinx-tabs, based off of what sphinx-panels is doing right now + a touch of JS would be much better on all those fronts IMO.

(aside: That isn't to say they aren't deficiencies or that they're not important to address - just that phrasing them as JS+CSS vs CSS-only feels wrong to me)

See if we can implement sync-ed tabs with CSS and HTML only

I tried this and gave up - there's an issue on sphinx-panels I filed about synchronized tabs, that has the story of me trying and giving up.

Only merge if it is maybe < 10 lines of JS or something.

It'll solve the problem, but... I don't see good reasons to do it this way. What are the pros of doing things this way?

One of the cons is that we'd basically have a component (tabs) that works without any of the others, works without bootstrap, that is provided as part of a library that defaults to you're gonna use bootstrap.

And we're gonna end up deprecating an existing package with an existing userbase for exactly the same functionality. It has a lot of scope for improvement... yes. :P

IOW, I don't think it's a good idea to deprecate an existing solution while creating a new one when both are basically different tradeoffs and mixing them actually gives us something better - especially since it's not making maintenance significantly easier and doesn't directly provide any benefits to the user. (oh god, this is like every Python Packaging discussion ever)

no one on jupyter-book has actually asked for yet

Welllll, I can't speak for jupyter-book users, but pip's documentation could realllly use some good looking synchronized tabs per-OS. I'm pretty sure that lots of Python projects might want this.

Right now, the choices are "old meh-looking heavy tabs based on semantic-UI" vs "clean looking tabs that don't depend on anything w/ added weight from everything else sphinx-panels provides". For a component that "just works" independently... Idk if I like any of these options.

---

bring "sphinx-panels tabs into sphinx-tabs"

In spirit of moving things forward, is anyone actively opposed to this idea? :)

This would mean rewriting sphinx-tabs, which shouldn't take more than 1 evening IMO, and deprecating the tabbed directive in sphinx-panels in favor of sphinx-tabs. FWIW, I'm pretty open to also adding that directive to sphinx-tabs, but we'll cross that bridge once we get there. :)

[akhmerov]

Perhaps this is a decent gauge in judging demand for grouped tabs: https://github.com/search?l=reStructuredText&q=group-tab&type=code

[choldgraf]

In spirit of moving things forward, is anyone actively opposed to this idea? :)

I'm not opposed to it. I didn't realize that sphinx-tabs had such a big userbase already. Given that fact, I'd be +1 on moving this into sphinx-tabs.

[chrisjsewell]

We can discuss it again when there is a viable alternative on the table.
Until that day, the tabbed directive will remain in sphinx-panels.

[choldgraf]

I think @pradyunsg proposed this alternative:

This would mean rewriting sphinx-tabs, which shouldn't take more than 1 evening IMO, and deprecating the tabbed directive in sphinx-panels in favor of sphinx-tabs.

I interpreted that as: re-write the current sphinx-tabs directives to be more lightweight and use the CSS approach that the sphinx-panels implementation uses. Then deprecate tabbed inside of sphinx-panels and recommend people use sphinx-tabs for tabs.

And in addition, if the tabbed directive pattern is something we want to keep:

FWIW, I'm pretty open to also adding that directive to sphinx-tabs, but we'll cross that bridge once we get there.

[chrisjsewell]

No by "on the table", I mean someone has actually written code.

Note we also have to consider that, given sphinx-tabs does have a biggish user-base, if those users are going to be happy if sphinx-tabs suddenly completely changes how it looks and perhaps works.

TBH it seems that @pradyunsg has a very specific design in mind, so I don't why you don't just write a new sphinx extension.
There's no rule against having multiple extensions with the same functionality, that users can choose between, but likely once this is in existence then we can decide if/where it should get moved / what it should replace.

[choldgraf]

So it sounds like for the purposes of this issue our strategy for tabbed content is:

• There are two sphinx extensions that handle tabbed content, sphinx-panels and sphinx-tabs. While they are both under executablebooks/, there is no direct plan to integrate them
• If somebody wants to re-write sphinx-tabs to be more streamlined, and replicates the functionality of sphinx-panels, then sphinx-panels may consider deprecating in favor of sphinx-tabs but no guarantees there
• Jupyter Book installs and documents sphinx-panels functionality on its own, and will recommend users use sphinx-tabs if they want more advanced tabs functionality (like synced tabs)