starlingx/docs
Code Issues Proposed changes

Document tab usage

Browse Source 
Add content to the Docs contributor guide on tab types and usage.

Change-Id: Ia32eeb766302c6231fff5e9531e3203660f1a6d2
Signed-off-by: Ron Stone <ronald.stone@windriver.com>
This commit is contained in:
Ron Stone 2024-01-19 16:17:23 +00:00
parent b517a5fdfb
commit 4b1d5cdc3b
1 changed files with 231 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

231
doc/source/contributor/doc_contribute_guide.rst
View File

@ -392,6 +392,237 @@ the file name/label string like this: ``architectural-considerations--d9dd4c105
.. end-create-rst-files
--------------------
Using tabbed content
--------------------
.. begin-using-tabbed-content
Content on the master branch can take advantage of the ``sphinx-tabs``
extension to organize content into tabs.
Tabs are useful for presenting alternate sets of content in a way that does not
require that the reader interact with sets that are not of interest. This is
particularly useful in procedures where some steps vary across two or more
variable factors. Rather than maintain two or more seperate procedures, tabs
can be used to show one of the alternate sets of content. For example, the
installation procedures make heavy use of tabs to allow the reader to switch
between virtual and bare-metal versions of the procedures. See
:ref:`aio_simplex_install_kubernetes_r7` for an example.
**Basic tabs**
Basic tabs are stand-alone. They have no relationship to other tabbed content
on a page.
.. code-block:: rst
.. tabs::
.. tab:: Apples
Apples are green, or sometimes red.
.. tab:: Pears
Pears are green.
.. tab:: Oranges
Oranges are orange.
.. tabs::
.. tab:: Apples
Apples are green, or sometimes red.
.. tab:: Pears
Pears are green.
.. tab:: Oranges
Oranges are orange.
**Nested tabs**
Tab sets can be defined within other tab sets. While this can be useful for
organizing logical hierarchies of information, care should be taken not to make
readers 'dig' for relevant content, making it unnecessarily difficult to find.
.. tip::
Remember that the organizational goal of tabs is hide irrelevant information
while *making all relevant information visible*.
.. code-block:: rst
.. tabs::
.. tab:: Stars
.. tabs::
.. tab:: The Sun
The closest star to us.
.. tab:: Proxima Centauri
The second closest star to us.
.. tab:: Polaris
The North Star.
.. tab:: Moons
.. tabs::
.. tab:: The Moon
Orbits the Earth
.. tab:: Titan
Orbits Jupiter
.. tabs::
.. tab:: Stars
.. tabs::
.. tab:: The Sun
The closest star to us.
.. tab:: Proxima Centauri
The second closest star to us.
.. tab:: Polaris
The North Star.
.. tab:: Moons
.. tabs::
.. tab:: The Moon
Orbits the Earth
.. tab:: Titan
Orbits Jupiter
**Group tabs**
Tab sets can be grouped so that switching to a tab with a certian name in one
set causes all other tab sets on the page to switch to the same tab. This can
be very useful when the same alternatives recur many times on the same page.
The reader only needs to select the tab that is relevant to them once to have
the entire page switch to the appropriate content.
Do this by using the ``.. group-tab::`` directive in place of the ``.. tab::``
directive and by being sure to label all tabs consistently across tab sets.
In the example below, a reader can switch all tab sets to :guilabel:`Linux`,
:guilabel:`Mac OSX`, or :guilabel:`Windows` by making the selection once, in
any of the tab sets.
.. code-block:: rst
.. tabs::
.. group-tab:: Linux
Linux tab content - tab set 1
.. group-tab:: Mac OSX
Mac OSX tab content - tab set 1
.. group-tab:: Windows
Windows tab content - tab set 1
.. tabs::
.. group-tab:: Linux
Linux tab content - tab set 2
.. group-tab:: Mac OSX
Mac OSX tab content - tab set 2
.. group-tab:: Windows
Windows tab content - tab set 2
.. tabs::
.. group-tab:: Linux
Linux tab content - tab set 3
.. group-tab:: Mac OSX
Mac OSX tab content - tab set 3
.. group-tab:: Windows
Windows tab content - tab set 3
Try it out for yourself here:
.. tabs::
.. group-tab:: Linux
Linux tab content - tab set 1
.. group-tab:: Mac OSX
Mac OSX tab content - tab set 1
.. group-tab:: Windows
Windows tab content - tab set 1
.. tabs::
.. group-tab:: Linux
Linux tab content - tab set 2
.. group-tab:: Mac OSX
Mac OSX tab content - tab set 2
.. group-tab:: Windows
Windows tab content - tab set 2
.. tabs::
.. group-tab:: Linux
Linux tab content - tab set 3
.. group-tab:: Mac OSX
Mac OSX tab content - tab set 3
.. group-tab:: Windows
Windows tab content - tab set 3
.. end-using-tabbed-content
------------------------
Automated quality checks
------------------------