Sphinx 的“only”和“ifconfig”指令有什么区别？

Question

Sphinx 知道两个用于条件内容的指令：

• 仅 => http://www.sphinx-doc.org/en/1.4.8/markup/misc.html#tags
• ifconfig => http://www.sphinx-doc.org/en/1.4.8/ext/ifconfig.html

它们有什么区别？

Answer 1

only

only 指令用于包含/排除基于tags 的内容。可以指定tags：

1. 在 conf.py 中（这种用法使 only 与 ifconfig 非常相似）

2. 将-t 标志用于sphinx-build（不能作为make 的标志，因为-t 是--touch 的--touch 标志）

   example.rst

   .. only:: draft
   
      This message only appears in drafts.
   

   命令

   $ sphinx-build  -t draft  -b html -d _build/doctrees . _build/html
   

3. 生成器的格式或名称。 这就是only 的亮点。 .. only:: html 内容只有在您使用 make html 等时才会生成。

   example.rst

   .. only:: html
   
      This message only appears in HTML output.
   

   命令

   $ make html
   

ifconfig

ifconfig 使您可以灵活地根据任何涉及在 conf.py 中注册的配置变量的 Python 表达式的真实性来包含内容。但是，这意味着您必须编辑 conf.py 以更改内容是包含还是排除。

结论

如果您希望在不编辑 conf.py 的情况下更改内容，则需要 only。 例如，我使用only 在我的 HTML 文档中包含一个目录（contents 指令），但不在我的 pdf 文档中（因为 LaTeX 自己生成这些内容）。