How can I configure Sphinx to conditionally exclude some pages?

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

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.