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指令用于include/exclude基于tags的内容。 tags可指定：

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

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

   标志

   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 使您可以灵活地包含基于任何 Python 表达式的真实性的内容，这些表达式涉及在 conf.py 中注册的配置变量。不过，这意味着您必须编辑 conf.py 以更改是包含还是排除内容。

结论

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