Conditional content by builder

.. if-builder:: comes from sphinx-simplepdf. Its body is contributed only when the argument names the builder that is running. rinx has exactly one builder, html, so a block naming any other builder is left out.

The directive takes one argument and no options. The name is matched case-insensitively, as it is upstream.

A block for this builder

This paragraph is inside .. if-builder:: html, so it is part of the page.

The name is matched case-insensitively, so this block is included too:

Written as HTML, included all the same.

A block for another builder

The next block names sphinx-simplepdf's own PDF builder, so nothing between here and the following section reaches the page — and nothing in it is reported, because naming another builder is the ordinary use of the directive rather than a mistake.

The body is spliced, not wrapped

This is what .. if-builder:: offers over Sphinx's own .. only::, and why sphinx-simplepdf's documentation recommends it: an included body is contributed to the enclosing document rather than nested inside a container, so headings, hyperlink targets and toctrees written inside it are real structure.

A heading written inside the block

The heading above is a genuine section of this page — it appears in the navigation and takes its level from this document's own adornment sequence. The target above it is a document target, so this reference resolves to it from outside the block.

Nested blocks

The directive nests, and each level is decided on its own.

The outer block is for this builder.

So is the inner one, so this line is on the page.

What is reported

An argument naming no builder anyone knows is reported as if-builder.unknown-builder and the block is left out. Upstream leaves it out silently, which makes a typo indistinguishable from a deliberate exclusion.

A directive with no argument names no builder at all. It is reported as if-builder.missing-builder and drawn as an error block quoting its source, so the content is not lost without trace.

.. if-builder::

   There is no builder name above, so this build cannot decide whether to keep
   this paragraph.

A selected block with no content is reported as if-builder.empty-body: the directive was written to contribute something and contributed nothing. The same emptiness on a branch that was not selected is silent, since only the taken branch can be wrong about it.