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: 5indexcoreutilsoecplottinginstallnewsglossary.. only:: private_versiontodo

Is there a simple way to accomplish this?

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_versionTitle
=====A private content

index.rst

.. toctree:::maxdepth: 3public-sample.rstprivate-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