Sphinx rst2pdf and role directives

Question

In a reStructuredText on Sphinx 2.x, I want to put a content that changes depending on the output format.

In any source document, say, index.rst, add the following lines:

.. role:: pdf(raw)
   :format: pdf

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

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

.. |foo| replace::
   :pdf:`PDF!`
   :latex:`LaTeX!`
   :html:`HTML!`

I am |foo|

I expect it shows "I am HTML!" when the output format is in HTML, "I am LaTeX!" if it's LaTeX (even after converting the product to PDF via pdflatex) and "I am PDF!" if it's PDF.

I make the HTML version using make html and I see only "I am HTML!" in a web browser as I expect:

Install rst2pdf. Put the following lines in conf.py:

extensions = [
    'rst2pdf.pdfbuilder'
]

pdf_documents = [(
    'index',
    u'testRst2Pdf',
    u'Test Title',
    u'Sarah Author')]

Make the PDF version with

sphinx-build -b pdf ./source/ ./build/

Update. Below is the output. No error. I ran this using WSL 1 (Ubuntu 18.04).

Running Sphinx v2.4.3
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [pdf]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
processing testRst2Pdf...
index
resolving references...
done
writing testRst2Pdf...
done
build succeeded.

I see "I am PDF! LaTeX! HTML!" that includes all the three items.

Is there any way to get either "I am PDF!" or "I am LaTeX!" in the PDF file?

Note.

Before reporting this behavior as a bug, someone help me check if it's unexpected behavior or as-designed.
This question is derived from the other I asked earlier: StackOverflow: "Sphinx: Use a different directive for a different output format".

rst2pdf is not Sphinx. It might not support all its directives. Do you see any warnings or errors, or can you enable them? — Steve Piercy, Feb 28 '20 at 07:41
No, no error. Please search this page with "Update. Below" and see the result I just added a minute ago. Would you recommend XeLaTeX better? — Culip, Feb 28 '20 at 13:50
I could reproduce this, the 3 substitutions appear instead of 1 when building with _rst2pdf_. — sinoroc, Feb 28 '20 at 16:15
Was there any update on this in 2022? I have been figuring out this from quite a long time. — Sushivam, Aug 30 '22 at 06:46

score 0 · Answer 1 · answered Aug 12 '20 at 09:04

rst2pdf does not really have conditionals, but you might find the --strip-elements-with-class switch useful? Put the optional pieces into a class name and then if that class doesn't make sense for this format, remove it with the switch.

Manual is here https://rst2pdf.org/static/manual.html#command-line-options and I also blogged (basically a longer version of this first paragraph) about this https://rst2pdf.org/static/manual.html#command-line-options if more information would be useful.

Sphinx rst2pdf and role directives

1 Answers1