Sphinx-tabs in documentation

[sarakonradi]

This issue opens a discussion on whether or not we want to keep.. tabs:: in the documentation.

An example of where tabs are currently used can be found in the installation instructions for NEST: https://nest-simulator.readthedocs.io/en/latest/installation/index.html

Tabs could also prove useful in the Part 4 PyNEST tutorial, as they can show a snippet vs. figure view of on- and off-grids: https://nest-simulator.readthedocs.io/en/latest/tutorials/pynest_tutorial/part_4_spatially_structured_networks.html

The problem with tabs, however, is that they do not render well when printed to PDF or on GitHub: https://github.com/nest/nest-simulator/blob/master/doc/installation/index.rst

The issue follows up on an earlier conversation with @clinssen and @terhorstd in #1410.

[clinssen]

It seems to be impossible to link directly to a particular tab. For example, from the NESTML documentation, I would like to link to the Anaconda installation instructions for NEST, but "conda" is on its own tab there (https://nest-simulator.readthedocs.io/en/stable/installation/index.html), so I can only link to the overall installation instructions page.

[sarakonradi]

@clinssen Good that you are pointing this out; I hadn't thought of this issue before. Yes, you can only link the overall page that contains the tabs.

Perhaps, in the long run, it would make sense to remove the tabs and present the content in a different way. For example, rather than having one installation index, there could be two pages: "Standard installation instructions" and "Advanced installation instructions". Each page could present the information within the tabs in the form of subsections. There could also be a :local: table of contents listing the operating systems at the top.

Any alternative suggestions are welcome.

[heplesser]

Given the problems with linking to tabs, I think we should remove tabs.

[terhorstd]

In an extensive discussion during this week's hackathon, we confirmed the move away from tabs.
The discussion broadened to a collection of decisions that @sarakonradi will put in a *doStyle Guide among other points the result of the discussion regardin tabs was:

• not use UI tabs, they hide information. If at all, use the harmonica "unfold section", even better is flat docs with right-side page index/TOC

[github-actions]

Issue automatically marked stale!