Sphinx: Use a different directive for a different output format

Question

Assume you have a reStructuredText document and want to export it in two formats using Sphinx 2.x: HTML and PDF.

You want to put some slightly different contents in these two formats. For example, the text "I am HTML" appears in the HTML version whereas "I am PDF" appears in the PDF version in the same location of the document.

Use a replace directive like below will give you "I am HTML" regardless of the export format.

.. |foo| replace:: HTML

⋮

I am |foo|

Can you use a different directive for a different export format?

Answer 1

This is a little clunky, but it works for me:

.. role:: latex(raw)
   :format: latex

.. role:: html(raw)
   :format: html

.. |foo| replace:: :latex:`LaTeX text`:html:`HTML text`
.. |bar| replace:: :latex:`other latex text`:html:`other html text`

Answer 2

A solution could be to define a rst_prolog (or rst_epilog) dynamically based on some tag.

conf.py:

prolog_for_html = """
.. |document_type| replace:: HTML
"""

prolog_for_latex = """
.. |document_type| replace:: latex
"""

if tags.has('html_prolog'):
    rst_prolog = prolog_for_html
elif tags.has('latex_prolog'):
    rst_prolog = prolog_for_latex

document.rst

This is a |document_type| document.

Makefile

html latex:
    sphinx-build -t $@_prolog -b $@ src build/$@

Answer 3

Sphinx's "only directive" should be your friend.

Note that this does not work in plain Docutils (where you may use the strip-classes configuration setting and class values like "no-html" to emulate the effect of .. only:: not ….