Sphinx RTD 主题不正确地嵌套副标题

Question

我有一个

index.rst

文件，其中包含使用

README.rst

指令包含的

.. include::

的内容。当使用

make latexpdf

或在 html 中使用

.. contents::

指令渲染此内容时，TOC 将正确渲染，如下所示：

Description
Installation
  - From PyPI
  - From GitHub
Usage
Implementation

格式正确的 pdf 输出的目录

但是，当使用 sphinx-rtd-theme 运行

make html

时，呈现如下：

   Description
[+]Installation
   From PyPI
   From GitHub
   Usage
   Implementation

侧边栏格式不正确

我尝试分别在

:maxdepth: / max_depth

指令和

.. toctree::

中调整

conf.py.html_theme_options

。这些似乎都没有任何区别，

:titlesonly:

、

collapse_navigation

或

:numbered:

也没有。我不确定这是 Sphinx 问题还是主题问题。我什至将

.. include::

指令拆分如下，以使

index.rst

更符合传统的 Sphinx

index.rst

结构，但这也没有什么区别。

.. include:: ../../README.rst
   :end-line: 3

.. toctree::
   :maxdepth: 3
   :caption: Contents:


.. include:: ../../README.rst
   :start-line: 4

我还测试了

style_nav_header_background

主题选项以确认

html_theme_options

正在使用（确实如此）。我尝试使用默认的 Alabaster 主题进行测试，但 Alabaster 根本不想生成任何侧边栏导航，即使包含了正确的侧边栏也是如此。最后，我安装并运行

rstcheck

来确认我的第一个是有效的，并且它没有检测到

README.rst

的错误。话虽如此，当扫描

index.rst

时，它抛出了以下 AttributeError:

WARNING:rstcheck_core.checker:An `AttributeError` error occured. This is most probably due to a code block directive (code/code-block/sourcecode) without a specified language. This may result in a false negative for source: 'docs/source/index.rst'. The reason can also be another directive. For more information see the FAQ (https://rstcheck-core.rtfd.io/en/latest/faq) or the corresponding github issue: https://github.com/rstcheck/rstcheck-core/issues/3.
Success! No issues detected.

这里有

README.rst

的相关片段供参考：

################
django-npi-field
################

Description
===========
**Django-npi-field** is a Django library which validates and stores 10-digit U.S. `National Provider Identifier (NPI)`_
numbers.

.. _`National Provider Identifier (NPI)`: \
   https://www.cms.gov/Regulations-and-Guidance/Administrative-Simplification/NationalProvIdentStand

Installation
============
From PyPI
---------
Using pip:

.. code-block:: zsh

   pip install django-npi-field

Answer 1

所以这似乎是 sphinx-rtd-theme 特有的问题，而不是 Sphinx 本身的问题。根据 Lex 在评论中的建议，我从 RTD 主题切换到 Groundwork 主题，它呈现得完美无缺。如果您遇到同样的问题，我建议您访问 sphinx-themes.org 并查看是否有另一个主题适合您喜欢的风格并且可以正常工作。