从主 TOCTree 隐藏 Sphinx 小节答案

【问题标题】：Hide Sphinx subsections from main TOCTree从主 TOCTree 隐藏 Sphinx 小节
【发布时间】：2013-02-23 00:32:34
【问题描述】：

是否可以从主 TOCTree 中隐藏 RST 文件中存在的一个（或所有）小节？

让我再描述一下：

index.rst

:doc:`Label <path/to/rst/file>`
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. toctree::

   Label <path/to/rst/file>
   Label <path/to/rst/file>

   Label of Children TOCTree <path/to/rst/children/file>

children/file.rst

Children Title
==============

.. toctree::

   Label of Grandchildren 1
   Label of Grandchildren 2


Subsection 1
------------

Subsection 2
------------

Subsection 3
------------

这些文件在构建后将生成主 TOCTree：

标签
标签
儿童标签
- 孙子标签 1
- 孙子标签 2
- 第 1 小节
- 第 2 小节
- 第 3 小节

而且我想隐藏子部分，只保留 TOCTrees，尽可能多和尽可能深。例如：

标签
标签
儿童标签
- 孙子标签 1
- 孙子标签 2

但是，如果点击了与儿童标签相关的超链接，则子部分将照常列出；

【问题讨论】：

也许titlesonly 选项是您正在寻找的。见sphinx-doc.org/markup/toctree.html。
我试过了，但它与我想要的完全相反，保留标题并隐藏孩子的 TOCTrees。
Non-TOC headings within a Restructuredtext page的可能重复

标签： python-sphinx sections toctree

【解决方案1】：

我花了一段时间才弄明白，但我想我终于明白了。 “诀窍”是您需要在包含 toc 的父 rst 和包含该部分的子 rst 中设置指令。

对我来说，我将 :maxdepth:1 和 :titlesonly: 添加到父级 rst 的 toc 中，然后将 :titlesonly: 添加到子级的 toc 中，效果很好。这使我可以在子级中进行分层子节格式，该子级格式正确呈现，但不会显示在 TOC 中。

【讨论】：

正是我需要的。我实际上特别希望 :maxdepth: 2 在我的 index.rst toctree 中，但即使 :titlesonly: 仍然可以很好地抑制我在子页面中定义的小节。

【解决方案2】：

“rubric”指令可以实现你想要的：

http://sphinx-doc.org/markup/para.html#directive-rubric

它不会以完全相同的方式生成章节标题，但至少它们不会出现在目录中

【讨论】：

【解决方案3】：

您可以使用toctree 的maxdepth 参数来设置TOC 的深度：

.. toctree::
    :maxdepth: 2

【讨论】：

【解决方案4】：

尝试将第 1 小节的 ------------------ 更改为 ******************* 等。此外，您可以制作多个目录树，每个目录树都有自己的最大深度，例如

.. toctree::
    :maxdepth: 2

    Label <path/to/rst/file>
    Label <path/to/rst/file>

.. toctree::
    :maxdepth: 1
    Label of Children TOCTree <path/to/rst/children/file>

【讨论】：

【解决方案5】：

您可以制作自己的标签

你想要的标题类型

|start-h3| My Title |end-h3|

在文件末尾写入

.. |start-h3| raw:: html

     <h3>

.. |end-h3| raw:: html

     </h3>

【讨论】：