Conditionally compile document sections in Sphinx

Question

We are planning on creating a user manual for our software project. Currently, everything related to the code is documented in Sphinx, and we would like to use Sphinx for the manual.

Since we are writing scientific/engineering software, there will be a lot of topics on things like stress, strain, numerical algorithms, etc. For each topic, we will have a few stages of information:

1. Basic information: This one or two sentence description can be used anywhere we need a short summary of the topic. Example: simple definition of mechanical stress.
2. More detailed description: This one paragraph explanation can be used as the opening to a help page, or a summary in a more detailed listing of topics. Example, a paragraph about mechanical stress introducing the equation for axial stress.
3. Technical information. This can be multiple paragraphs on how the topic applies to the problems encountered by users of our software.
4. Code information. This will be documentation related to where the topic is encountered in the code. For example, we can point to our implementation of a certain numerical algorithm. We can use sphinx-apidoc like we currently do.

As you can see, the information gradually gets more complex. We would like to manage each topic in their own .rst file, and get the required information as needed. For example, maybe we want to use the basic information section in a tooltip. In the actual help menu, we can use the detailed description in a table of contents on a certain class of topics. In the full article on the topic, like what would be present in a full pdf manual, we can present the technical information along with the basic and more detailed descriptions. Lastly, we would like to keep code information only in our internal documentation.

It would be nice to keep all of the information for a single topic in one file, but to conditionally compile different sections based on the documentation we are generating.

Is there a built-in way to do something like this in Sphinx? If someone is doing something similar, can you tell us about it and give us some highlights of your workflow?

Answer 1

In past I wanted to compile two docs, a public and a private but I didn't want to split my source file (rst).

First step I found the only directive and I thought it was the solution. But when I wanted a entire full rst file in just public or private documentation I can't without indent the whole file.

So I write my own Sphinx plugin (scope) to manage all my case. To succeed I used the meta directive that can be place on the top of the file.

Thus

a_doc_for_basic.rst

.. meta::
    :scope: basic

Title
=====

My content

a_doc_for_code.rst

.. meta::
    :scope: code

Title
=====

My content

And you can continue to use .. only:: directive on file

a_doc_for_all.rst

Title
=====

My content

.. only:: code

    a piece of code

You can find plugin source here

As you can see the plugin is pretty simple and works thanks to regexp. That means (regexp) that there is 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

After that you can build your doc using the following command

sphinx-build ... -t <tag> ...

sphinx-build ... -t code ...

Other thing, you can use the same toctree for all tag because when compiling a doc per tag the toctree will be edited by the plugin to generate a tree without reference to the no-matching documentation.

PS: my plugin is not perfect but I replied to my needs, you can inspired and update it.