python - 如何使用 Sphinx 创建一个不会出现在目录树中的标题？

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>

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

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

score 5 · Accepted Answer

hidden您是否尝试添加toctree指令？就像是：

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

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

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

至于“节标题”（标题和副标题），来自Sphinx 官方文档的摘录可能会给你一个答案：

通常，没有为某些字符分配标题级别，因为结构是根据标题的连续性确定的。

您可能会尝试^为您的小节使用字符来呈现您需要的标题。

score 2 · Accepted Answer

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

简短的回答：

我想在页面上添加字幕，但我不希望它们出现在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
定义——引用文本（来自该链接）
如果您只想显示树中文档的标题，而不是同一级别的其他标题，您可以使用titlesonly 选项：
```
.. toctree::
  :titlesonly:
  foo
  bar
```

细节：

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

此处的文档Section Headers：

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

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

使用指令:titlesonly:下的.. toctree::选项，这些“标题”又名Section Headers将不会呈现在目录树中（并且只会.rst显示文件的“标题”）。

不带 `:titlesonly:`选项的示例：

如果您.. toctree::看起来像这样（没有选项:titlesonly:）：
然后呈现 TOC ，列出
页面.rst标题
及其：Section Headers

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

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

python - 如何使用 Sphinx 创建一个不会出现在目录树中的标题？

2 回答 2

简短的回答：

细节：

不带 `:titlesonly:`选项的示例：

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

相关但不同的范围：

python - 如何使用 Sphinx 创建一个不会出现在目录树中的标题？

2 回答 2

简短的回答：

细节：

不带 :titlesonly:选项的示例：

存在 选项的示例:titlesonly:：

相关但不同的范围：

Related

Reference

不带 `:titlesonly:`选项的示例：

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