python - 如何有条件地将文件包含在 Sphinx 'toctree' 中？

Question

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

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

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

Answer 1

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

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

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

.. meta::
    :scope: private_version

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

Title
=====

A public content

私人样本.rst

.. meta::
    :scope: private_version

Title
=====

A private content

索引.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

如您所见，toctree两者都有参考，但如果您不使用标签构建，插件将在编译期间删除private-sample.rstprivate

所以使用

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

会生成toctree如下：

• 公共样本.rst
• 私人样本.rst

但是如果你用

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

或者

sphinx-build ...

会toctree看起来像

• 公共样本.rst

我的插件不是 100% 完美的，但我只是一小段易于理解的代码，因此您可以随意编辑 :)

了解限制：

局限性：

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