Sphinx rst2pdf 和角色指令答案

【问题标题】：Sphinx rst2pdf and role directivesSphinx rst2pdf 和角色指令
【发布时间】：2020-06-12 02:42:31
【问题描述】：

在 Sphinx 2.x 上的 reStructuredText 中，我想放置一个根据输出格式而变化的内容。

在任何源文档中，比如 index.rst，添加以下行：

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

当输出格式为 HTML 时，我希望它显示 “我是 HTML！”，如果是 LaTeX（即使在转换产品之后），“我是 LaTeX！”通过 pdflatex 转换为 PDF）和 “我是 PDF！”（如果是 PDF）。

我使用make html 制作了 HTML 版本，但正如我所料，我在网络浏览器中只看到 “我是 HTML！”：

安装rst2pdf。将以下行放入conf.py：

extensions = [
    'rst2pdf.pdfbuilder'
]

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

制作PDF版本

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

更新。 下面是输出。没有错误。我使用 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.

我看到“我是 PDF！LaTeX！HTML！”，其中包括所有三个项目。

有什么方法可以在 PDF 文件中获取 “我是 PDF！” 或 “我是 LaTeX！”？

注意。

在将此行为报告为错误之前，请有人帮我检查它是否是意外行为或符合设计。
这个问题源自我之前提出的另一个问题：StackOverflow: "Sphinx: Use a different directive for a different output format"。

【问题讨论】：

您也可以在 Google 群组 sphinx-users 上提问。
rst2pdf 不是狮身人面像。它可能不支持它的所有指令。您是否看到任何警告或错误，或者您可以启用它们吗？
不，没有错误。请使用“更新。下方”搜索此页面，然后查看我刚刚添加的结果。你会推荐 XeLaTeX 更好吗？
我可以重现这一点，使用 rst2pdf 构建时出现 3 个替换而不是 1 个。

标签： python-sphinx restructuredtext rst2pdf

【解决方案1】：

rst2pdf 实际上没有条件，但您可能会发现 --strip-elements-with-class 开关有用吗？将可选部分放入类名中，然后如果该类对这种格式没有意义，请使用开关将其删除。

手册在这里https://rst2pdf.org/static/manual.html#command-line-options，如果更多信息有用的话，我还在博客上（基本上是第一段的较长版本）关于这个https://rst2pdf.org/static/manual.html#command-line-options。

【讨论】：