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

Question

这个问题已经有答案了:

Conditional toctree in Sphinx (4 个回答)

已关闭 8 年前。

我想仅在设置特定标签时将我的文件之一包含在 Sphinx TOC 中，但是明显的方法失败了:

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

有没有简单的方法可以实现这一点？

Answer 1

过去，我需要能够从同一个源文件编译两个文档:公共(public)文档和私有(private)文档。

为了成功，我必须编写自己的插件(您可以找到 here )。

当我有一个文件仅包含在私有(private)文档中时，我只需在文件顶部添加以下指令(强制)

.. meta::
    :scope: private_version

public-sample.rst(没什么特别的)

Title
=====

A public content

私有(private)样本.rst

.. meta::
    :scope: private_version

Title
=====

A private content

index.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

正如您在 toctree 上看到的，有两个引用，但如果您不使用标签构建，插件将在编译期间删除 private-sample.rst 私有(private)

所以使用

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

将生成toctree，例如:

• 公共(public)样本.rst
• 私有(private)样本.rst

但是如果你使用

构建

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

或

sphinx-build ...

toctree 看起来像

• 公共(public)样本.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