python-sphinx - 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

这有点笨拙，但对我有用：

.. 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

一个解决方案可能是基于某个标签（例如，可能是构建器标签）动态定义一个rst_prolog（或）。rst_epilog

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/$@