I think this is simply a documentation issue (possibly not even on this project) - but finding out what I'd done wrong below was time-consuming, frustrating and (to me at least) quite obscure.
I was in the process of migrating a project to using sphinx-external-toc after successfully using it with an another project. I find the top-down approach much easier to understand than the default sphinxtoctree system. Both projects have pretty much identical setups and we're using Python 3.11 to build docs with the following:
In the project being updated, I'd generated a first pass at the new ToC using sphinx-etoc from-project source. However the expected table of contents was not appearing in the built documents. There wasn't an error - just that the table of contents bar contained a short table of the headings for the single page. Comparing the resulting HTML for the two projects:
the functioning one contains a full tree with (e.g.) <li class="toctree-l1"> elements on all pages
the other just had <div class="local-toc"> for each page.
My initial thought was that my _toc.yml file was bad in some way - which is what lead me to using sphinx-etoc - but the lack of build errors made that seem unlikely. In the end, a line by line comparison of the conf.py files showed that I had:
Switching to includehidden=True revealed my new ToC.
I don't think I've missed a 'gotcha' page somewhere and couldn't find an issue or discussion on this and it was wildly annoying 😄
Reproduce the bug
This might be specific to sphinx_rtd_theme or might be wider but basically set includehidden=False in the html_theme_options in conf.py
List your environment
poetry show
alabaster 0.7.16 A light, configurable Sphinx theme
appnope 0.1.4 Disable App Nap on macOS >= 10.9
asttokens 2.4.1 Annotate AST trees with source code positions
attrs 23.2.0 Classes Without Boilerplate
autodocsumm 0.2.12 Extended sphinx autodoc including automatic autosummaries
babel 2.15.0 Internationalization utilities
certifi 2024.6.2 Python package for providing Mozilla's CA Bundle.
cfgv 3.4.0 Validate configuration and produce human readable error messages.
cftime 1.6.4 Time-handling functionality from netcdf4-python
charset-normalizer 3.3.2 The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet.
click 8.1.7 Composable command line interface toolkit
cloudpickle 3.0.0 Pickler class to extend the standard pickle.Pickler functionality
comm 0.2.2 Jupyter Python Comm implementation, for usage in ipykernel, xeus-python etc.
contourpy 1.2.1 Python library for calculating contours of 2D quadrilateral grids
coverage 7.5.4 Code coverage measurement for Python
cycler 0.12.1 Composable style cycles
dask 2023.12.1 Parallel PyData with Task Scheduling
debugpy 1.8.2 An implementation of the Debug Adapter Protocol for Python
decorator 5.1.1 Decorators for Humans
distlib 0.3.8 Distribution utilities
docutils 0.20.1 Docutils -- Python Documentation Utilities
dpath 2.2.0 Filesystem-like pathing and searching for dictionaries
executing 2.0.1 Get the currently executing AST node of a frame, and other information
fastjsonschema 2.20.0 Fastest Python implementation of JSON schema
filelock 3.15.4 A platform independent file lock.
fonttools 4.53.0 Tools to manipulate font files
fsspec 2024.6.0 File-system specification
hypothesis 6.104.1 A library for property-based testing
identify 2.5.36 File identification library for Python
idna 3.7 Internationalized Domain Names in Applications (IDNA)
imagesize 1.4.1 Getting image size from png/jpeg/jpeg2000/gif file
importlib-metadata 8.0.0 Read metadata from Python packages
iniconfig 2.0.0 brain-dead simple config-ini parsing
ipykernel 6.29.4 IPython Kernel for Jupyter
ipython 8.25.0 IPython: Productive Interactive Computing
isort 5.13.2 A Python utility / library to sort Python imports.
jedi 0.19.1 An autocompletion tool for Python that can be used for text editors.
jinja2 3.1.4 A very fast and expressive template engine.
jsonschema 4.22.0 An implementation of JSON Schema validation for Python
jsonschema-specifications 2023.12.1 The JSON Schema meta-schemas and vocabularies, exposed as a Registry
jupyter-cache 1.0.0 A defined interface for working with a cache of jupyter notebooks.
jupyter-client 8.6.2 Jupyter protocol implementation and client libraries
jupyter-core 5.7.2 Jupyter core package. A base package on which Jupyter projects rely.
kiwisolver 1.4.5 A fast implementation of the Cassowary constraint solver
latexcodec 3.0.0 A lexer and codec to work with LaTeX code in Python.
locket 1.0.0 File-based locks for Python on Linux and Windows
markdown-it-py 3.0.0 Python port of markdown-it. Markdown parsing, done right!
markupsafe 2.1.5 Safely add untrusted strings to HTML/XML markup.
matplotlib 3.9.0 Python plotting package
matplotlib-inline 0.1.7 Inline Matplotlib backend for Jupyter
mdformat 0.7.17 CommonMark compliant Markdown formatter
mdformat-frontmatter 0.4.1 An mdformat plugin for parsing / ignoring frontmatter.
mdformat-tables 0.4.1 An mdformat plugin for rendering tables.
mdit-py-plugins 0.4.1 Collection of plugins for markdown-it-py
mdurl 0.1.2 Markdown URL utilities
mypy 1.10.1 Optional static typing for Python
mypy-extensions 1.0.0 Type system extensions for programs checked with the mypy type checker.
myst-nb 1.1.0 A Jupyter Notebook Sphinx reader built on top of the MyST markdown parser.
myst-parser 3.0.1 An extended [CommonMark](https://spec.commonmark.org/) compliant parser,
nbclient 0.10.0 A client library for executing notebooks. Formerly nbconvert's ExecutePreprocessor.
nbformat 5.10.4 The Jupyter Notebook format
nest-asyncio 1.6.0 Patch asyncio to allow nested event loops
netcdf4 1.7.1.post1 Provides an object-oriented python interface to the netCDF version 4 library
nodeenv 1.9.1 Node.js virtual environment builder
numpy 1.26.4 Fundamental package for array computing in Python
packaging 24.1 Core utilities for Python packages
pandas 2.2.2 Powerful data structures for data analysis, time series, and statistics
parso 0.8.4 A Python Parser
partd 1.4.2 Appendable key-value storage
pexpect 4.9.0 Pexpect allows easy control of interactive console applications.
pillow 10.3.0 Python Imaging Library (Fork)
pint 0.20.1 Physical quantities module
platformdirs 4.2.2 A small Python package for determining appropriate platform-specific dirs, e.g. a `user data dir`.
pluggy 1.5.0 plugin and hook calling mechanisms for python
pre-commit 2.21.0 A framework for managing and maintaining multi-language pre-commit hooks.
prompt-toolkit 3.0.47 Library for building powerful interactive command lines in Python
psutil 6.0.0 Cross-platform lib for process and system monitoring in Python.
ptyprocess 0.7.0 Run a subprocess in a pseudo terminal
pure-eval 0.2.2 Safely evaluate AST nodes without side effects
pybtex 0.24.0 A BibTeX-compatible bibliography processor in Python
pybtex-docutils 1.0.3 A docutils backend for pybtex.
pydocstyle 6.3.0 Python docstring style checker
pygments 2.18.0 Pygments is a syntax highlighting package written in Python.
pyparsing 3.1.2 pyparsing module - Classes and methods to define and execute parsing grammars
pytest 7.4.4 pytest: simple powerful testing with Python
pytest-cov 3.0.0 Pytest plugin for measuring coverage.
pytest-datadir 1.5.0 pytest plugin for test data directories and files
pytest-mock 3.14.0 Thin-wrapper around the mock package for easier use with pytest
python-dateutil 2.9.0.post0 Extensions to the standard Python datetime module
pytz 2024.1 World timezone definitions, modern and historical
pyyaml 6.0.1 YAML parser and emitter for Python
pyzmq 26.0.3 Python bindings for 0MQ
referencing 0.35.1 JSON Referencing + Python
requests 2.32.3 Python HTTP for Humans.
rpds-py 0.18.1 Python bindings to Rust's persistent data structures (rpds)
ruamel-yaml 0.18.6 ruamel.yaml is a YAML parser/emitter that supports roundtrip preservation of comments, seq/map flow style, and map key order
ruamel-yaml-clib 0.2.8 C version of reader, parser and emitter for ruamel.yaml derived from libyaml
scipy 1.14.0 Fundamental algorithms for scientific computing in Python
shapely 2.0.4 Manipulation and analysis of geometric objects
six 1.16.0 Python 2 and 3 compatibility utilities
snowballstemmer 2.2.0 This package provides 29 stemmers for 28 languages generated from Snowball algorithms.
sortedcontainers 2.4.0 Sorted Containers -- Sorted List, Sorted Dict, Sorted Set
sphinx 7.3.7 Python documentation generator
sphinx-external-toc 1.0.1 A sphinx extension that allows the site-map to be defined in a single YAML file.
sphinx-rtd-theme 2.0.0 Read the Docs theme for Sphinx
sphinxcontrib-applehelp 1.0.8 sphinxcontrib-applehelp is a Sphinx extension which outputs Apple help books
sphinxcontrib-bibtex 2.6.2 Sphinx extension for BibTeX style citations.
sphinxcontrib-devhelp 1.0.6 sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp documents
sphinxcontrib-htmlhelp 2.0.5 sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files
sphinxcontrib-jquery 4.1 Extension to include jQuery on newer Sphinx releases
sphinxcontrib-jsmath 1.0.1 A sphinx extension which renders display math in HTML via JavaScript
sphinxcontrib-mermaid 0.9.2 Mermaid diagrams in yours Sphinx powered docs
sphinxcontrib-qthelp 1.0.7 sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp documents
sphinxcontrib-serializinghtml 1.1.10 sphinxcontrib-serializinghtml is a sphinx extension which outputs "serialized" HTML files (json and pickle)
sqlalchemy 2.0.31 Database Abstraction Library
stack-data 0.6.3 Extract data from python stack frames and tracebacks for informative displays
tabulate 0.9.0 Pretty-print tabular data
tomli-w 1.0.0 A lil' TOML writer
toolz 0.12.1 List processing tools and functional utilities
tornado 6.4.1 Tornado is a Python web framework and asynchronous networking library, originally developed at FriendFeed.
tqdm 4.66.4 Fast, Extensible Progress Meter
traitlets 5.14.3 Traitlets Python configuration system
types-dataclasses 0.6.6 Typing stubs for dataclasses
types-jsonschema 4.22.0.20240610 Typing stubs for jsonschema
types-tqdm 4.66.0.20240417 Typing stubs for tqdm
typing-extensions 4.12.2 Backported and Experimental Type Hints for Python 3.8+
tzdata 2024.1 Provider of IANA time zone data
urllib3 2.2.2 HTTP library with thread-safe connection pooling, file post, and more.
virtualenv 20.26.3 Virtual Python Environment builder
wcwidth 0.2.13 Measures the displayed width of unicode strings in a terminal
xarray 2024.6.0 N-D labeled arrays and datasets in Python
zipp 3.19.2 Backport of pathlib-compatible object wrapper for zip files
Describe the bug
I think this is simply a documentation issue (possibly not even on this project) - but finding out what I'd done wrong below was time-consuming, frustrating and (to me at least) quite obscure.
I was in the process of migrating a project to using
sphinx-external-tocafter successfully using it with an another project. I find the top-down approach much easier to understand than the defaultsphinxtoctreesystem. Both projects have pretty much identical setups and we're using Python 3.11 to build docs with the following:In the project being updated, I'd generated a first pass at the new ToC using
sphinx-etoc from-project source. However the expected table of contents was not appearing in the built documents. There wasn't an error - just that the table of contents bar contained a short table of the headings for the single page. Comparing the resulting HTML for the two projects:<li class="toctree-l1">elements on all pages<div class="local-toc">for each page.My initial thought was that my
_toc.ymlfile was bad in some way - which is what lead me to usingsphinx-etoc- but the lack of build errors made that seem unlikely. In the end, a line by line comparison of theconf.pyfiles showed that I had:Switching to
includehidden=Truerevealed my new ToC.I don't think I've missed a 'gotcha' page somewhere and couldn't find an issue or discussion on this and it was wildly annoying 😄
Reproduce the bug
sphinx_rtd_themeor might be wider but basically setincludehidden=Falsein thehtml_theme_optionsinconf.pyList your environment