Support for headings in tabs

[Jakob933]

We use sphinx-tabs in the Open Source project ONAP by the Linux Foundation.

Unfortunately we did not find a way to show headings in tabs. This means we can't create sections and can not reference to them in toc's. It would be really helpful for us to have a solution for this issue.

Example:

Heading1
++++++++++++++

.. tabs::

   .. tab:: Testtab

      Heading 2
      +++++++++++++

Heading 3
+++++++++++++

[foster999]

@chrisjsewell do you know if it's possible to nest a heading inside another reST directive?

I tried with .. note:: and it gave the same WARNING: Unexpected section title., so I suspect not.

[stefanodavid]

HI @foster999 I am 99% sure that headings are in some sense "absolute" and can not be part of any other element or, like in your case, directives. This is not even a sphinx issue, but it is due to the underlying docutils implementation.

I tried in the past to put a heading within an only:: directive, but it failed with the same warning as yours: WARNING: Unexpected section title. The only solution I could find was to organise the content in a different way and move the heading outside the directive.

[Daltz333]

I think an alternative is to "fake" the heading with the appearance of the heading. Although this might not be obvious to the user.

[foster999]

Thanks @stefanodavid, it does look like this is the case.

As @Daltz333 mentioned, you can fake headings in appearance but won't be able to create direct links to them. The easiest way I've found to do this is using HTML h tags in your content.

[stefanodavid]

Yes, I agree that a fake heading would work, but it is IMHO a poor workaround: it would not be maintainable, in won't show up in either toctree:: or content:: directives, and you would mimic it for every builder you need. @foster999, can you share your use case, so that perhaps someone can suggest an alternative?