Skip to content

"only" directive guarding "contents" directive broken by docutils 0.22 #14002

@bradking

Description

@bradking

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions