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 the

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`