Sphinx中的条件toctree

Question

我想做多个版本的文档,这些版本在包含的部分中有所不同.为此,我通常使用唯一的指令或ifconfig扩展名.但是,我不能将任何与toctree指令结合使用.

我基本上想要的是这样的:

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   .. only:: university
      complex

有没有办法做到这一点？

Answer 1

一个非常简单的解决方案是用不同的名称维护两个单独的索引文件。您可以指定默认使用哪个索引文件，并在命令行上conf.py使用特殊构建来覆盖它。-D master_doc=alternate-indexsphinx-build

Answer 2

如果您有目录的层次结构，我之前的答案就会失败，所以我编写了一个简单的toctree-filt指令，该指令能够根据条目的前缀过滤条目。例如，给定一个toctree-filt指令，如

.. toctree-filt::
   :maxdepth: 1

   user-manual
   :internal:supervisor-api
   :draft:new-feature
   :erik:erik-maths
   api

并将排除列表设置为['draft','erik']将产生一个有效的目录树，看起来像

.. toctree-filt::
   :maxdepth: 1

   user-manual
   supervisor-api
   api

将以下行添加到您的conf.py：

.. toctree-filt::
   :maxdepth: 1

   user-manual
   :internal:supervisor-api
   :draft:new-feature
   :erik:erik-maths
   api

将以下代码放在/sphinx_ext您的/source目录旁边：

.. toctree-filt::
   :maxdepth: 1

   user-manual
   supervisor-api
   api

现在只需将您现有的toctree指令更改为toctree-filt，您就可以开始使用了。请注意，Sphinx 会发布错误，因为它会查找文档中未包含的文件。不知道如何解决这个问题。

Answer 3

据我所知，没有办法做你想做的事。我一直在努力解决同样的问题，请参阅https://github.com/sphinx-doc/sphinx/issues/1717。

原因是 Sphinx 将目录树节点中包含的所有行处理为纯文本。

我看到两种选择：

1. 您可以编写自己的 toctree 指令；

2. 您可以扩展目录树，包括包含要计算的表达式的选项

   .. toctree:
      :condition: expression
   
      file1
   

然后自定义 doctree 解析事件。

3. 您可以在定义您自己的标签的原始文本上使用文本替换。您可以为源读取事件实现一个事件处理程序。例如$$condition$$可以包含要评估的条件，而$$$块的末尾，即

   .. toctree:
   
      file1
      $$mycondition$$
      file2
      $$$
   

根据mycondition，您可以删除以下块行。

3号非常简单，而对我来说2号是最优雅的。