Sphinx: Use a different directive for a different

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

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

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 2

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`