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
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
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
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.