sphinx-doc / sphinx-doc/sphinx

toctree does not consider "only" directive

Open
#9,819 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

directives:only internals:toctree type:bug
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.

Screen Shot 2021-11-04 at 4 57 51 PM

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.