如何使用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
**********

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

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

可以在此处找到构建文档，它不包含副标题，因为它会破坏文档的当前结构。

Answer 1

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

\n

简短回答：

\n

\n

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

\n

\n

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

\n

.. toctree::\'s的文档:titlesonly:在这里：

\n

\n
• https://www.sphinx-doc.org/en/master/usage/restructedtext/directives.html#table-of-contents
\n
• 下Directives> Table of contents> .. toctree::> Additional options>titlesonly option
\n
• 定义 -- 引用的文本（来自该链接）\n

  \n

  如果您只想显示树中文档的标题，而不显示其他\n同一级别的标题，则可以使用 Titlesonly 选项：

  \n

  .. toctree::\n  :titlesonly:\n  foo\n  bar\n

  \n

  \n
\n

\n

细节：

\n

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

\n

此处的文档Section Headers：

\n

\n
• https://www.sphinx-doc.org/en/master/usage/restructedtext/basics.html#sections
\n
• 定义 -- 从该链接引用的文本:\n

  \n

  节标题 ( ref ) 是通过使用标点符号在节标题上加下划线（以及可选的上划线）来创建的，至少与文本一样长：

  \n

  =================\nThis is a heading\n=================\n

  \n

  ...

  \n

  \n
  • # 带上划线，用于零件
  \n
  • * 带上划线，用于章节
  \n
  • =，对于部分
  \n
  • -，对于小节
  \n
  • ^, 对于小节
  \n
  • “，对于段落
  \n

  \n

  \n
\n

\n

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

\n

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

\n
\n
\n\n

不带 选项的示例:titlesonly:：

\n
\n

\n
• 如果你.. toctree::看起来像这样（没有选项:titlesonly:）：
  \n\xc2\xa0
  \n
  
\n
• 然后呈现目录
  \n列出.rst页面标题
  \n及其：Section Headers \
  n\xc2\xa0
\n

\n
\n
\n\n

存在选项的 示例:titlesonly:：

\n
\n

\n
• 如果你的.. toctree::看起来像这样（带有选项:titlesonly:）：
  \n\xc2\xa0
  \n
  
\n
• 然后呈现目录\n仅
  列出页面标题\ n但不列出其包含的内容：\n\xc2\xa0.rst
Section Headers
  
\n

\n\n
\n
\n

相关但范围不同：

\n

这个答案（上面）是针对.. toctree::指令的。

\n

更改侧边栏需要不同的步骤，并且这些步骤可能会有所不同，具体取决于您在 Sphinx 中使用的自定义主题。

\n

如果您还想修改侧边栏显示的目录，这里有一些相关链接可以帮助您开始：

\n

\n
• https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
\n
• https://www.sphinx-doc.org/en/master/faq.html?highlight=sidebar#how-do-i
\n
• https://www.sphinx-doc.org/en/master/usage/theming.html?highlight=sidebar
\n
• so/q/14477396 ：如何在Sphinx中展开侧边栏目录树上的所有小节？
\n
• so/q/18969093 ：如何在每个页面的侧边栏中包含目录树
\n

\n

（我会为此列出更多详细信息，但我仍在调查。我目前正在寻找一种方法（1）Section Headers使用在侧边栏目录中显示sphinx_rtd_theme，但（2）不在插入Section Headers中显示.. toctree::.)

\n

Answer 2

你尝试添加hidden在你的toctree指令？就像是：

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

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

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

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

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

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