-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
Closed
Labels
Description
Describe the bug
We use the .. only:: directive to limit rendering of a reST .. contents:: table of contents to only specific document formats.
With docutils 0.22, this pattern causes a [docutils] diagnostic:
ERROR: The "contents" directive may not be used within topics or body elements.
I bisected the problem to docutils r10225.
How to Reproduce
$ cat index.rst
Title
*****
.. only:: html
.. contents::
Section
=======
$ >conf.py
$ sphinx-build -M html . _build
...
/.../index.rst:6: ERROR: The "contents" directive may not be used within topics or body elements. [docutils]
...Environment Information
Platform: linux; (Linux-6.16.12+deb14+1-amd64-x86_64-with-glibc2.41)
Python version: 3.13.9 (main, Oct 15 2025, 14:56:22) [GCC 15.2.0])
Python implementation: CPython
Sphinx version: 8.3.0+/e347e59cc
Docutils version: 0.22.2
Jinja2 version: 3.1.6
Pygments version: 2.19.2
Reactions are currently unavailable