CODEWITHSUNDEEP
python-sphinxconditional-compilation
Flag
Flag

Reputation: 577

Generate internal and external docs from single source using Sphinx

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?

Upvotes: 2

Views: 626

Answers (2)

Flag
Flag

Reputation: 577

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

Upvotes: 0

Steve Piercy
Steve Piercy

Reputation: 15105

The Sphinx extension ifconfig might do what you want, although you would have to indent content.

Upvotes: 2

Related Questions