How do I conditionally include a file in a Sphinx 'toctree'?

Question

I would like to include one of my files in my Sphinx TOC only when a certain tag is set, however the obvious approach fails:

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

Is there a simple way to accomplish this?

Answer 1

In a past I had a need to be able to compile two documentations from the same source file: a public and a private.

To succeed I had to write my own plugin (that you can find here).

When I have a file to be only on private documentation I just add this following directive on the top of the file (mandatory)

.. meta::
    :scope: private_version

public-sample.rst (nothing special)

Title
=====

A public content

private-sample.rst

.. meta::
    :scope: private_version

Title
=====

A private content

index.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

As you can see on toctree there is the both reference, but the plugin will remove the private-sample.rst during compilation if you'r not building with tag private

So using

sphinx-build ... -t private_version ...

Will generate toctree like:

• public-sample.rst
• private-sample.rst

but if you build with

sphinx-build ... -t other ...

or

sphinx-build ...

the toctree will look like

• public-sample.rst

My plugin is not 100% perfect but I just a small piece of code a easy to understand so you can edit like you want :)

Know limitations:

limitation:

• The directive .. meta:: :scope: must be place at the top of the file (no line before)
• The directive .. meta:: :scope: must match the regexp ^.. meta::\s+:scope: ([a-zA-Z0-9_-]+)
• The directive .. meta:: :scope: can manage multiple tag but you can easily update the plugin for your needs
• Plugin deviate the original use of meta directive docutils.sourceforge.net/docs/ref/rst/directives.html#meta