Use Conditional Text

Sphinx supports conditional text. That is, you can specify that some content is visible only to the intended audience. You can then build different versions of the project for different audiences

To limit visibility of certain content, indent that content under an .. only:: directive. For example, to specify that some content is available only to internal audiences, use:

.. only:: Internal

  Content to be included only in the internal version of the document.

Build Projects with Conditions

When you use conditions, you must use the -t audience flag in the build command to specify which version of the project to build.

For example, the default command to build HTML in a project Makefile is:

.PHONY: html
 @echo "Build finished. The HTML pages are in $(BUILDDIR)."

If you use this command (make html) to build the project, the resulting HTML will not include content indented under the .. only:: Internal directive.

To build a project that does include this conditional content, add a command to your Makefile with the parameter -t Internal:

.PHONY: internalhtml
  @echo "Build finished. The HTML pages are in $(INTERNALBUILDDIR)."

Then build the project with make internalhtml. The resulting HTML will include the internal-only content.


This example assumes you have defined INTERNALBUILDDIR as a separate location for the built files. You do not want to place them in the same directory as those files built without the conditional text, and have them overwrite the other project.