sphinx-doc / sphinx-doc/sphinx
toctree does not consider "only" directive
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
toctree when used in templates does not consider .. only directive.
In index.rst Use .. only to only add some documents for singlehtml builder.
In the template, using toctree, and building multi-page html, all the toc tree shows up.
Since this is a multi-page html build, should the .. only cause the toctree to only have two?
How to Reproduce
Use sphinx-quickstart to set up a project with any values.
Update source/index.rst with this toc:
.. only:: singlehtml_builder
.. toctree::
one
.. toctree::
:maxdepth: 2
:caption: Contents:
two
Create source/one.rst and source/two.rst.
Create a custom _templates/layout.html that uses toctree():
{% extends "!layout.html" %}
{%- block sidebar1 %}
{{ super() }}
{{ toctree() }}
{% endblock %
sphinx-build html
Open build/html/index.html
Expected behavior
TOC only contains link to "two"
Your project
https://github.com/ngzhian/sphinx-repro
Screenshots
No response
OS
Linux
Python version
3.9.7
Sphinx version
4.2.0
Sphinx extensions
No response
Extra tools
No response
Additional context
No response
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the behavior from source/index.rst with the custom _templates/layout.html and its toctree() call, using sphinx-build html. Compare the generated index.html TOC against the expected single link to "two"; done means the .. only directive is respected in the template-rendered TOC.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100