如何有条件地在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

公开-样品.rst（没什么特别的）

^{pr2}$

私人-样品.rst

.. meta::
    :scope: private_version

Title
=====

A private content

索引.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

正如您在toctree上看到的，这两个引用都有，但是插件会删除私有的-样品.rst在编译期间，如果不使用标记private生成

所以使用

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

将生成toctree，如下所示：

• 公开-样品.rst在
• 私人-样品.rst在

但是如果你用

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

或者

sphinx-build ...

toctree看起来像

• 公开-样品.rst在

我的插件不是百分之百完美，但我只是一小段代码，很容易理解，所以你可以编辑你想要的：）

了解限制：

限制：

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