狮身人面像的条件 [英] Conditional toctree in Sphinx

问题描述

我想做多个版本的文档，其中包含的部分不同。为了实现这一点，我通常会使用只有指令或 ifconfig 扩展名。但是，我不能使用与 toctree 指令相结合的任何一种。 p>

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

  .. toctree： ：
：maxdepth：2 
 
简介
字符串
数据类型
数字
 ..唯一::大学
复杂
  

有没有办法？

解决方案

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

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

我看到两种选择：

1. 你可以编写自己的toctree指令;



2. 您可以扩展包含包含待评估表达式的选项的toctree

     .. toctree： 
   ：条件：表达式
    
    file1 
     

然后您自定义doctree解决方案事件。

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

     .. toctree：
    
    file1 
    $$ mycondition $$ 
    file2 
    $$$ 
     

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

第3号很简单，而对我来说数字2是最优雅的。

I want to do multiple versions of a documentation, which differ in the sections that are included. To achieve this I would usually use either the only directive or the ifconfig extension. However, I cannot use any of those in combination with the toctree directive.

What I basically want is something like this:

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   .. only:: university
      complex

Is there a way to do that?

解决方案

As far as I know there is no way to do what you would like. I have been struggling with the same issue, see https://github.com/sphinx-doc/sphinx/issues/1717.

The reason is that Sphinx process all lines contained in a toctree node as pure text.

I see two alternatives:

1. you can write your own toctree directive;

2. you can extend the toctree including an option that contains the expression to be evaluated

   .. toctree:
      :condition: expression
   
      file1
   

and then you customize the doctree resolve event.

3. you can use text substitutions on the raw text defining your own tags. you can do that implementing an event handler for the source-read event. For instance $$condition$$ could contain the condition to be evaluated, while $$$ the end of the block, i.e.

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

Depending on mycondition, you can remove the following block lines.

Number 3 is quite simple, while to me number 2 is the most elegant.

这篇关于狮身人面像的条件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！