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

Question

我正在使用 Sphinx 为 Python 模块创建文档。

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

我想要小部分和简短（几行）描述。将每个部分标题添加到 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>

With a github README.md adding more # characters will result in smaller titles. What is the equivalent in *.rst?

The build documentation can be found here and it does not contain subtitles since it would ruin the current structure of the docs.

Answer 1

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

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

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

This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive – this makes sense if you intend to insert these links yourself, in a different style, or in the HTML sidebar.

至于 "section headers"（标题和副标题）official Sphinx documentation 中的这段摘录可能会给您答案：

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.

您可以尝试在小节中使用 ^ 字符来呈现您需要的标题。

Answer 2

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

简答：

I wold like to add subtitles on a page but I don't want them to appear in the toctree.

您正在寻找 .. 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
定义 -- 引用文本（来自link）
If you want only the titles of documents in the tree to show up, not other headings of the same level, you can use the titlesonly option:
```
.. toctree::
  :titlesonly:
  foo
  bar
```

详情：

我假设您 do 希望示例的 .. toctree:: 指令中的所有 .rst 条目出现在目录中（table 的内容），Sphinx 插入其中，但您不希望这些 .rst 文件中的任何 Section Headers 出现在该目录中。

此处 Section Headers 的文档：

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
定义 -- 引用自 link 的文字：
Section headers (ref) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:
```
=================
This is a heading
=================
```
...
- # with overline, for parts
- * with overline, for chapters
- =, for sections
- -, for subsections
- ^, for subsubsections
- ", for paragraphs

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

使用 .. toctree:: 指令下的 :titlesonly: 选项，这些“标题”a.k.a。 Section Headers 不会在 TOC 树中呈现（只会显示 .rst 文件的“标题”）。

示例没有 `:titlesonly:` 选项：

如果您的 .. toctree:: 看起来像这样（没有 :titlesonly: 选项）：
然后渲染目录
列出 .rst 个页面标题
还有他们的Section Headers:

示例 with `:titlesonly:` 选项存在：

如果您的 .. toctree:: 看起来像这样（with :titlesonly: 选项）：
然后渲染目录
仅列出 .rst 个页面标题
但不它们包含 Section Headers:

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

How to create a title that will not appear in the toctree with Sphinx?

python

python-sphinx

toctree

简答：

详情：

示例没有 `:titlesonly:` 选项：

示例 with `:titlesonly:` 选项存在：

相关，但范围不同：

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

How to create a title that will not appear in the toctree with Sphinx?

python

python-sphinx

toctree

简答：

详情：

示例 没有 :titlesonly: 选项：

示例 with :titlesonly: 选项存在：

相关，但范围不同：

示例没有 `:titlesonly:` 选项：

示例 with `:titlesonly:` 选项存在：