如何在Sphinx 'toctree'中有条件地包含一个文件？

Question

当设置了特定标签时，我希望在Sphinx TOC中仅包含我的文件之一，然而，显而易见的方法失败了：

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

有没有简单的方法实现这个？

- orome

Answer 1

曾经，我需要从同一个源文件编译出两份文档：公开的和私密的。

为了达成这个目的，我不得不编写自己的插件（你可以在这里找到它）。

当我需要将文件放到私密文档中时，我只需在文件顶部添加以下指令（必填）：

.. meta::
    :scope: private_version

public-sample.rst（没有特殊情况）

。

Title
=====

A public content

private-sample.rst

.. meta::
    :scope: private_version

Title
=====

A private content

index.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

如您在 toctree 中所看到的，有两个参考文献，但如果您不使用标签 private 进行构建，则插件会在编译期间删除 private-sample.rst

因此，请使用：

sphinx-build ... -t private_version ...

将生成toctree如下：

• public-sample.rst
• private-sample.rst

但如果使用以下命令构建，则不会包含在内：

sphinx-build ... -t other ...

或者

sphinx-build ...

toctree将如下所示：

• public-sample.rst

我的插件并非完美无缺，但我只写了一小段易于理解的代码，使您可以根据需要进行编辑 :)

已知限制：

限制：

• 指令.. meta:: : scope:必须位于文件顶部（无行）
• 指令.. meta:: : scope: 必须与 regexp ^.. meta::\s+:scope: ([a-zA-Z0-9_-]+) 匹配
• 指令.. meta:: :scope: 可以管理多个标记，但是您可以轻松更新插件以满足自己的需求
• 插件偏离了 meta 指令 docutils.sourceforge.net/docs/ref/rst/directives.html#meta 的原始用途

- Kakawait

---

我认为你应该提供一个链接到http://docutils.sourceforge.net/docs/ref/rst/directives.html#meta，并解释一下你是如何“滥用”`meta`指令的。 - mzjn

你是否知道如何消除所有“WARNING: toctree contains reference to nonexisting document u'private-sample.rst'”消息？我正在使用您的脚本（谢谢！）来排除许多文件，但我收到了很多这些警告。 - calys

@calys 在每个文件的顶部放置 :orphan: 以消除警告。 - 0leg