Hide single section in Sphinx documentation

Question

I couldn't find a directive that handles this.

Suppose to have a single rst document and for some reason you want to hide a single section during the build (no matter if HTML, PDF..), like:

Visible section
===============
Here some example I want to show


Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document

is there a .. hidden:: directive that handle this, I'm thinking of something like:

Visible section
================
Here some example I want to show

.. hidden::

Not visible section
===================
Some text that I have written but for the current build I want to hide from the final document

.. visible::

Another section
===============
Other visible section in both text and final document

Isn't your question answered there?: https://stackoverflow.com/questions/49701524/private-sections-of-text-possible-in-restructuredtext-files — aflp91, Apr 15 '18 at 18:02
Partially thanks. I found something useful here: https://stackoverflow.com/questions/8313476/how-can-i-configure-sphinx-to-conditionally-exclude-some-pages — matteo, Apr 17 '18 at 12:20
If you start a line with two dots and then a space it does not show up in the documentation. In fact Sphinx automatically creates a section like this and it does not show up: — user3425506, Jul 18 '19 at 22:02

user3425506 · Answer 1 · 2019-07-26T20:39:27.093

You can use comment syntax: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#comments

The version of Sphinx I have got automatically generates an index.rst file that starts with a comment like this:

.. sphinx-quickstart on Sat Jun 22 15:48:19 2019.
   You can adapt this file completely to your liking, etc

It does not show up in the documentation. You can start lines with two dots and a space followed by your own text and that does not show up either. You need to make sure that all the lines you create are indented the same as the first line. Then the whole section does not show up. Also make sure there is an empty line before the section and after it (unless it is the first section in the file or the last one)

What you are describing is the comment syntax: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#comments — mzjn, Jul 22 '19 at 06:46

score 1 · Answer 2 · answered May 06 '21 at 08:28

Here is a solution to hide a section, so it doesn't show up in the HTML ouput. However, this does not affect the build.

The idea is to use the class diretive and that way be able to assign a CSS class to the section(s). In CSS you can then define the class with display: none (or any other CSS).

For you example it would look like (note the identation):

Visible section
================
Here some example I want to show

.. class:: hidden

   Not visible section
   ===================
   Some text that I have written but for the current build I want to hide from the final document

Another section
===============
Other visible section in both text and final document

In your css you add the following styling:

.hidden { display: none }

Here is a link that explains how to add custom CSS to Sphinx.

Hide single section in Sphinx documentation

2 Answers2