如何有条件地将文件包含在 Sphinx 'toctree' 中？ [复制]答案

【问题标题】：How do I conditionally include a file in a Sphinx 'toctree'? [duplicate]如何有条件地将文件包含在 Sphinx 'toctree' 中？ [复制]
【发布时间】：2014-02-26 06:03:10
【问题描述】：

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

.. toctree::
   :maxdepth: 5

   index
   core
   utils
   oec
   plotting

   install
   news

   glossary

   .. only:: private_version

      todo

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

【问题讨论】：

标签： python conditional-statements python-sphinx toctree

【解决方案1】：

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

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

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

.. meta::
    :scope: private_version

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

Title
=====

A public content

private-sample.rst

.. meta::
    :scope: private_version

Title
=====

A private content

index.rst

.. toctree::
    :maxdepth: 3

    public-sample.rst
    private-sample.rst

正如您在toctree 上看到的那样，两者都有参考，但如果您没有使用标签private 构建，插件将在编译期间删除 private-sample.rst p>

所以使用

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

会生成toctreelike：

public-sample.rst
私人样本.rst

但是如果你用

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

或

sphinx-build ...

toctree 看起来像

public-sample.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

【讨论】：

我认为您应该提供指向docutils.sourceforge.net/docs/ref/rst/directives.html#meta 的链接并解释您“滥用”meta 指令。
您是否知道如何摆脱所有“警告：toctree 包含对不存在的文档 u'private-sample.rst' 的引用”消息？我正在使用您的脚本（谢谢！！）排除许多文件，并且收到很多警告。
@calys 将 :orphan: 放在每个文件的顶部，导致警告将其抑制。