Conditional toctree in Sphinx

Question

I want to do multiple versions of a documentation, which differ in the sections that are included. To achieve this I would usually use either the only directive or the ifconfig extension. However, I cannot use any of those in combination with the toctree directive.

What I basically want is something like this:

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   .. only:: university
      complex

Is there a way to do that?

Answer 1

A very simple solution is to maintain two separate index files under different names. You can specify which index file to use by default in conf.py and override it for a special build using -D master_doc=alternate-index on the sphinx-build command line.