Hide Single Section in Sphinx Documentation

Sphinx is a powerful documentation generator that allows you to create beautiful and informative documentation for your projects. However, there may be times when you want to hide certain sections of your documentation from the final output. This can be useful for keeping sensitive information private or for excluding sections that are not yet complete.

Hiding sections in Sphinx documentation is relatively easy to do, and there are a few different methods you can use. In this blog post, we will discuss three different methods for hiding sections in Sphinx documentation.

Method 1: Using Comments

The first method involves using comments to hide sections of your documentation. Comments are ignored by Sphinx when it generates the final output, so you can use them to hide any text, code, or images that you don't want to appear in the final documentation.

To hide a section using comments, simply add two dots (:) followed by a space at the beginning of each line in the section you want to hide. For example, to hide the following section:

Hidden Section
==============
This is a hidden section.
    

You would add two dots (:) followed by a space to the beginning of each line in the section, like this:

.. Hidden Section
.. ==============
.. This is a hidden section.
    

When you generate the final documentation, the hidden section will not appear.

Method 2: Using the class Directive

The second method for hiding sections in Sphinx documentation involves using the class directive. This method allows you to assign a CSS class to a section of your documentation, and then use CSS to hide the section from the final output.

To use the class directive, you first need to create a CSS class that will be used to hide the section. You can do this by adding the following CSS to your theme/sphinx/static/css/theme.css file:

.hidden {
  display: none;
}
    

Once you have created the CSS class, you can use the class directive to assign it to a section of your documentation. To do this, add the following line to the beginning of the section you want to hide:

.. class:: hidden
    

When you generate the final documentation, the section with the hidden class will be hidden from the output.

Method 3: Using the "strip-elements-with-classes" Setting

The third method for hiding sections in Sphinx documentation involves using the strip-elements-with-classes setting. This setting allows you to specify a list of CSS classes that should be removed from the final output.

To use the strip-elements-with-classes setting, you need to add the following line to your conf.py file:

    strip_elements_with_classes = ['hidden']
    

Once you have added the strip_elements_with_classes setting, any sections that have the hidden CSS class will be removed from the final output.

These are just a few of the methods that you can use to hide sections in Sphinx documentation. The method you choose will depend on your specific needs.