Question

我正在使用sphinx为python模块创建文档。

我希望在页面上添加字幕，但我不希望它们出现在 toctree 中。

我想要小部分和短（几行）描述。将每个部分标题添加到 toctree 会使文档浏览更加困难。

这是我的 index.rst ：

Welcome to ModernGL's documentation!
====================================

.. figure:: Examples/images/02_uniforms_and_attributes.png
    :scale: 50 %
    :alt: ModernGL
    :align: center
    :figclass: align-center

Start `here <ModernGL.html>`_.

.. toctree::
    :maxdepth: 4
    :caption: Contents:

    ModernGL <ModernGL.rst>
    Examples <Examples.rst>
    Contributing <Contributing.rst>


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

我想添加一些字幕：

Subtitle 1
**********

Subtitle 2
**********

Subtitle 3
**********

Subtitle 4
**********

我检查了文档，我不知道应该使用哪种类型的下划线。不确定是否存在将标题转换为<h4>或<h5>

的特殊下划线

使用github README.md 添加更多#字符会导致较小的标题。 *。rst 中的等价物是什么？

可以找到构建文档here并且它不包含字幕，因为它会破坏文档的当前结构。

Answer 1

您是否尝试在toctree指令中添加hidden？类似的东西：

.. toctree::
    :maxdepth: 4
    :hidden:
    :caption: Contents:

    ModernGL <ModernGL.rst>
    Examples <Examples.rst>
    Contributing <Contributing.rst>

这仍然会通知Sphinx文档层次结构，但不会在指令的位置插入文档中的链接 - 如果您打算自己插入这些链接，以不同的样式或HTML侧边栏插入这些链接，这是有意义的。

至于＃34;节标题＆＃34; （标题和副标题）official Sphinx documentation的摘录可能会给你一个答案：

通常情况下，没有为某些字符指定标题级别，因为结构是从标题的连续性确定的。

您可以尝试使用^字符作为子部分来渲染出您需要的标题。

Answer 2

时间戳：此答案的 sphinx-doc.org 摘录来自 2021 年 5 月。

简答：

<块引用>

我想在页面上添加字幕，但我不希望它们出现在目录树中。

您正在寻找 .. toctree:: 指令的 :titlesonly: 选项。

.. toctree:: 的 :titlesonly: 文档在这里：

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents
在Directives下 > Table of contents > .. toctree:: > Additional options > titlesonly option
定义——引用文本（来自该链接） <块引用>
如果您只想显示树中文档的标题，而不显示其他同级别的标题，可以使用titlesonly选项：
```
.. toctree::
  :titlesonly:
  foo
  bar
```

详情：

我假设您确实希望示例的 .rst 指令中的所有 .. toctree:: 条目都出现在 Sphinx 在那里插入的 TOC（目录）中，但您不希望这些 Section Headers 文件中的任何 .rst 出现在该目录中。

此处为 Section Headers 的文档：

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
定义 -- 来自该链接的引用文本： <块引用>
节标题 (ref) 是通过使用标点字符（至少与文本一样长）为节标题加上下划线（和可选上划线）来创建的：
```
=================
This is a heading
=================
```
...
- # 带上划线，用于部分
- * 带上划线，用于章节
- =，对于部分
- -，用于小节
- ^，用于小节
- "，用于段落

默认情况下，如果 :titlesonly: 指令下没有 .. toctree:: 选项，呈现的 TOC 树将显示列出的 .rst 文件的“标题”以及任何 {{1} } 列在这些 Section Headers 文件中。

使用 .rst 指令下的 :titlesonly: 选项，这些“标题”又名 .. toctree:: 不会在 TOC 树中呈现（只有 {{1} }} 文件将被显示）。

示例没有 `Section Headers` 选项：

如果您的 .rst 看起来像这样（没有 :titlesonly: 选项）：
然后呈现TOC
列出 .. toctree:: 个页面标题
和还有他们的:titlesonly:：

示例 `.rst` 选项存在：

如果您的 Section Headers 看起来像这样（带有 :titlesonly: 选项）：
然后呈现TOC
仅列出.. toctree::页标题
但不是它们包含的:titlesonly:：

如何创建一个不会出现在Sphinx的toctree中的标题

2 个答案:

简答：

详情：

示例没有 `Section Headers` 选项：

示例 `.rst` 选项存在：

相关，但范围不同：

如何创建一个不会出现在Sphinx的toctree中的标题

2 个答案:

简答：

详情：

示例没有 Section Headers 选项：

示例 .rst 选项存在：

相关，但范围不同：

示例没有 `Section Headers` 选项：

示例 `.rst` 选项存在：