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

Question

我想在我的Sphinx TOC中包含我的一个文件，只有在设置某个标签时才会这样做，但显而易见的方法失败了：

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

有一种简单的方法可以实现这一目标吗？

Answer 1

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

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

如果我的文件只在私人文档上，我只需在文件顶部添加以下指令（必填）

.. meta::
    :scope: private_version

public-sample.rst（没什么特别的）

Title
=====

A public content

<强>私人sample.rst

.. meta::
    :scope: private_version

Title
=====

A private content

<强> index.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

正如您在toctree上看到的那样，有两个引用，但如果您没有使用标记{{1}构建，则插件将在编译期间删除 private-sample.rst }}

所以使用

private

将生成sphinx-build ... -t private_version ... ，如：

• 公共sample.rst
• 私有sample.rst

但如果你用

构建

toctree

或

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

sphinx-build ... 看起来像

• 公共sample.rst

我的插件不是100％完美，但我只是一小段易于理解的代码，因此您可以按照自己的意愿进行编辑：）

了解限制：

不限于：

• 指令.. meta :: scope：必须放在文件的顶部（之前没有行）
• 指令.. meta :: scope：必须匹配regexp ^ .. meta :: \ s +：scope：（[a-zA-Z0-9 _-] +）
• 指令.. meta :: scope：可以管理多个标签，但您可以根据需要轻松更新插件
• 插件偏离toctree指令的原始用途docutils.sourceforge.net/docs/ref/rst/directives.html#meta