Search code examples
pythonpython-sphinxrestructuredtextread-the-docs

Sphinx RTD Theme improperly nesting subheadings

I have a single index.rst file that has the contents of my README.rst included using the .. include:: directive. When rendering this using make latexpdf or using the .. contents:: directive in html, the TOC is rendered properly as the following:

Description
Installation
  - From PyPI
  - From GitHub
Usage
Implementation

The properly formatted pdf output's TOC The properly formatted pdf output's TOC

When running make html using sphinx-rtd-theme, however, this is rendered as follows:

   Description
[+]Installation
   From PyPI
   From GitHub
   Usage
   Implementation

The improperly formatted sidebar The improperly formatted sidebar

I’ve tried adjusting :maxdepth: / max_depth in both the .. toctree:: directive and in conf.py.html_theme_options respectively. Neither of these seemed to make any difference, nor did :titlesonly:, collapse_navigation, or :numbered:. I’m unsure if this is a Sphinx issue or a theme issue. I’ve even split the .. include:: directive as below to make the index.rst more in-line with traditional Sphinx index.rst structure, but this also made no difference.

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

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


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

I've also tested the style_nav_header_background theme option to confirm html_theme_options are being used (they are). I attempted to test with the default Alabaster theme, but Alabaster didn't want to generate any sidebar navigation at all, even with the proper sidebars included. Finally, I installed and ran rstcheck to confirm that my rst is valid and it detected no errors for README.rst. That being said, when scanning index.rst, it threw the following 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.

Here's a relevant snippet of README.rst for reference:

################
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
Solution

  • So this appears to be an issue specifically with the sphinx-rtd-theme, not with Sphinx itself. On Lex’s recommendation in the comments, I switched from the RTD theme to the Groundwork theme and it rendered flawlessly. If you’re having the same issue, I recommend going to sphinx-themes.org and seeing if there is another theme that fits your preferred style and works properly.