如何通过在 python-sphinx 中使用角色来使用唯一的内联指令？

Question

在 python-sphinx 中，有 only 指令，可用于根据文档的输出有条件地影响文档。例如，文本仅以 html 或 Latex 形式出现。

使用方法如下：

.. 仅:: 不是乳胶

   这里有一些文本，没有出现在乳胶输出中。

..仅:: html

   这里有一些文本，仅出现在 html 输出中。

如何以正确的方式使用角色指令来使用唯一类内联，让我们这样说：

这里有一些文本，:only-notlatex:`不会出现在latex中`
:only-html:`只出现在html中`。

我在原始指令中看到了类似的内容。这对于唯一的指令也可能吗？我试过：

..作用::only-html(仅)
   ：格式：html

.. 作用:: only-notlatex(only)
   ：格式：非乳胶

但这不起作用。

Answer 1

指令适用于文本块（整个段落）；角色用于内联文本（段落内）。

您提到了

raw

，确实有一个具有该名称的指令和角色，用于“原始数据传递”。

但是没有与

only

指令等效的内置角色。为此，您必须创建自己的自定义角色。我无法提供任何详细说明，但这里有一篇文章可以帮助您入门：http://doughellmann.com/2010/05/09/defining-custom-roles-in-sphinx.html.

Answer 2

对于依赖于输出的内联内容，您可以考虑可以嵌套在“only”指令中的替换。

.. only:: html
   .. |content| replace:: ham
.. only:: latex
   .. |content| replace:: spam

或者，也许是带有要跳过的课程的自定义角色：

.. role:: no-latex
.. role:: no-html

I want to eat :no-latex:`ham` :no-html:`spam`.

与 Docutils 的 strip-classes 配置设置一起使用。