diff --git a/guides/contributing.rst b/guides/contributing.rst index 928585308a..9b555b710b 100644 --- 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