add collapse and tab examples to guides/contributing.rst (#4359)

* added collapsible sections to guides/contributing.rst * lint issue 1 * lint issue 2 * lint issue 3 * consistency fix * consistency fix 2 * added interleaved examples * lint fix * added tab examples * lint fix * fixed glitch * Update guides/contributing.rst Co-authored-by: Keith Burzinski <kbx81x@gmail.com> --------- Co-authored-by: Keith Burzinski <kbx81x@gmail.com>
2025-03-01 03:51:36 +01:00 · 2024-10-21 14:15:07 +05:30 · 2024-10-21 14:15:07 +05:30 · b99a7c6a07
commit b99a7c6a07
parent 4d329c6055
1 changed files with 159 additions and 0 deletions
--- a/guides/contributing.rst
+++ b/guides/contributing.rst
@ -251,6 +251,165 @@ adhere to the following order:

      Note that a blank line is *required* after every ``code-block`` directive.

+- **Collapsible section**: To add a collapsible section, use the ``collapse`` directive:
+
+  .. code-block:: rst
+
+      .. collapse:: Details
+
+          Something small enough to escape casual notice.
+
+  .. collapse:: Details
+
+      Something small enough to escape casual notice.
+
+  .. code-block:: rst
+
+      .. collapse:: A long code block
+
+          .. code-block:: yaml
+
+              # Sample configuration entry
+              switch:
+                - platform: gpio
+                  name: "Relay #42"
+                  pin: GPIOXX
+
+  .. collapse:: A long code block
+
+      .. code-block:: yaml
+
+          # Sample configuration entry
+          switch:
+            - platform: gpio
+              name: "Relay #42"
+              pin: GPIOXX
+
+  The ``:open:`` flag can be used to have the section open by default.
+
+  .. code-block:: rst
+
+      .. collapse:: Open
+          :open:
+
+          This section is open by default.
+
+  .. collapse:: Open
+      :open:
+
+      This section is open by default.
+
+  .. note::
+
+      - The ``:open:`` flag must immediately follow the ``collapse`` directive without a blank line between them.
+      - A blank line is *required* after every ``collapse`` directive.
+
+- **Tabs**: To group content into tabs, use the ``tabs`` directive. The tabs directive defines a tab set.
+  Basic tabs are added using the ``tab`` directive (without s), which takes the tab’s label as an argument:
+
+  .. code-block:: rst
+
+      .. tabs::
+
+          .. tab:: Apples
+
+              Apples are green, or sometimes red.
+
+          .. tab:: Pears
+
+              Pears are green.
+
+          .. tab:: Oranges
+
+              Oranges are orange.
+
+  This will appear as
+
+  .. tabs::
+
+      .. tab:: Apples
+
+          Apples are green, or sometimes red.
+
+      .. tab:: Pears
+
+          Pears are green.
+
+      .. tab:: Oranges
+
+          Oranges are orange.
+
+  Tabs can also be nested inside one another:
+
+  .. 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
+
+  .. note::
+
+      - A blank line is *required* after every ``tabs`` directive.
+      - The contents of each tab can be displayed by clicking on the tab that you wish to show.
+        Clicking again on the tab that is currently open will hide its content, leaving only the tab set labels visible.
+      - For advanced features like tab-groupings, refer to https://sphinx-tabs.readthedocs.io/en/latest/
+
 - **Images**: Use the ``figure`` directive to display an image:

  .. code-block:: rst