Python 如何有条件地将文件包含在Sphinx'；toctree'；？

仅当设置了某个标记时，我才想在Sphinx TOC中包含我的一个文件，但是明显的方法失败了：

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

---

有没有一种简单的方法可以做到这一点？

在过去，我需要能够从同一个源文件中编译两个文档：公共文档和私有文档

为了成功，我必须编写自己的插件（你可以找到）

当我有一个文件仅在私人文档中时，我只需在文件顶部添加以下指令（强制）

public-sample.rst（无特殊要求）

私人样本。rst

.. meta::
    :scope: private_version

Title
=====

A private content

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

index.rst

.. meta::
    :scope: private_version

Title
=====

A private content

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

正如您在

toctree

上看到的，这两个引用都有，但是如果您不使用标记

private

构建，插件将在编译期间删除private sample.rst

所以使用

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

将生成目录树，如：

• 公共样本
• private-sample.rst

但是如果你用

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

或

目录树将如下所示

• 公共样本

我的插件不是100%完美，但我只是一小段代码，很容易理解，所以你可以随意编辑：）

了解限制：

限制：

• 指令。。meta:：：范围：必须放在文件的顶部（前面没有行）
• 指令。。meta:：：作用域：必须与regexp^.匹配。。meta:：\s+：范围：（[a-zA-Z0-9_u-]+）
• 指令。。meta:：：范围：可以管理多个标记，但您可以根据需要轻松更新插件
• 插件偏离了原来使用的

  meta

  directive docutils.sourceforge.net/docs/ref/rst/directives.html#meta

---

我认为您应该提供链接并解释您“滥用”了

meta

指令。您是否知道如何消除所有“警告：目录树包含对不存在的文档u'private-sample.rst'的引用”消息？我正在使用您的脚本（谢谢！！）来排除许多文件，我收到了很多这样的警告。@calys将

：orphan:

放在每个文件的顶部，导致警告被抑制。

sphinx-build ...