Generate internal and external docs from single source using Sphinx

Question

I'm trying to find information on Sphinx's ability to tag certain bits of documentation as 'internal' and build it like sphinx-build -b -include internal source output where the -include flag would contain a series of tags to include in the output.

That would allow me to generate 2 versions (or more) of my docs while keeping it single-source.

Example:

.. audience::internal

Page title
============

This whole page will be available only in the internal docs.

or

Page title
============

This whole page will be available in the internal and external docs. 

.. audience::internal

That p will only be available in the internal docs.

This p will be available in the internal and external docs.

Is there such a mechanism? If not, would that be difficult to create?

Answer 1

ifconfig is one way to do this indeed, but after asking around, it seems that there is a better mechanism:

.. only:: directive

Use it to tag something:

.. only:: internal

   Page title
   ============

   This whole page will be available only in the internal docs.

Then you can run a build with the -t option to publish everything tagged with internal (or whatever you used)

sphinx-build -t internal -b html source output