How can I configure Sphinx to conditionally exclud

Question

When generating documentation using Sphinx, I would like to be able to generate two versions of my documentation: one including everything, and one with only a particular set of pages. What's the best way of achieving that?

I could write a build script that moves files around to achieve this but it would be really nice if there was a way to tell sphinx to exclude or include particular documents during a particular build.

Answer 1

The only and ifconfig directives can be used to apply conditions within pages.

There does not seem to be any simple way to use conditions to completely exclude entire pages (.rst files).

The following (in index.rst) excludes the reference to doc2.html in the toctree in index.html when generating HTML output:

.. toctree::
   doc1.rst

.. only:: latex

   .. toctree::
      doc2.rst

But this does not really work. The doc2.html file is still generated, and it is reachable via the "Next topic" link when doc1.html is the current topic.

Answer 2

How about sphinx.ext.ifconfig? You set config values in your conf.py file. As that is a regular Python file, you can make your inclusion criteria smart and automatic if you need to.

Answer 3

Maybe my answer comes a bit late, but I managed to do this with Sphinx via exclude patterns in the config file.

My documentation is partly for users and partly for admins.
Some pages have file names that contain the word admin, and like you, I wanted to build two versions: one with everything (the admin docs) and one with all "admin" pages excluded (the user docs).

To exclude all "admin" pages in all subfolders, you have to add this line to the config file conf.py:

exclude_patterns = ['**/*admin*']

That was the easy part.

My problem was that I didn't know how to run the build two times, one with and one without the exclude patterns without using two different config files.

I didn't find a solution by myself, so I asked a question here on SO and got an answer:

• The config file is just a Python file and can contain Python code, which will be executed on build.
• You can pass parameters ("tags") via the command line which can be queried in the config file.

So I have this exclude pattern in my config file:

exclude_patterns = ['**/*admin*']
if tags.has('adminmode'):
    exclude_patterns = []

Now I can run the build without passing anything, which will exclude the "admin" files:

make clean
make html

⇒ this is my user documentation

...and I can set the "adminmode" tag, which will not exclude anything:
(Windows command line syntax)

set SPHINXOPTS=-t adminmode
make clean
make html

⇒ this is my admin documentation.

---

Bonus:

I can use the same tag to ignore some specific content on a page, by Including content based on tags.

Example:

regular documentation
=====================

This paragraph and its headline will always be visible.

.. only:: adminmode

        secret admin stuff
        ------------------

        This paragraph will be visible in the admin docs only.


This will (again) always be visible.