How can I conditionally include a file in "toctree" Sphinx?

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 an easy way to do this?

Answer 1

In the past, I needed to compile two documents from the same source file: public and private.

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

When I have a file only in private documentation, I just add this following directive to the top of the file (required)

 .. 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 are both links, but the plugin will remove private-sample.rst at compile time if you don't create the private tag

So using

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

Will generate toctree as:

• community-sample.rst
• private-sample.rst

but if you create using

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

or

 sphinx-build ... 

toctree will look like

• community-sample.rst

My plugin is not 100% perfect, but I'm just a small piece of code that is easy to understand, so you can edit as you want:

Know the limitations:

restriction:

• Directive .. meta: scope: should be at the top of the file (without a line)
• The .. meta: scope: directive must match regexp ^ .. meta :: \ s +: scope: ([a-zA-Z0-9 _-] +)
• The .. meta: scope: directive can manage multiple tags, but you can easily update the plugin for your needs.
• The plugin rejects the original use of the meta directive docutils.sourceforge.net/docs/ref/rst/directives.html#meta li>