sphinx-doc / sphinx-doc/sphinx

Allow to specify toctree pages as direct-children of parent page

Open
#8,287 6 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

internals:toctree type:enhancement
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Currently, all pages listed in a toctree directive will be listed as children of the last header level under which the toctree is placed. For example:

My title
========

My header
---------

.. toctree::

   page1

Will turn into:

1. My title
1.1 My header
1.1.1 page1 title

However, I find that many users use the index page similar to an "introduction" to the chapter, and put headers on that page. They really wish for the toctree to be treated as siblings of the index page top-level headers, rather than as children of the latest header. E.g. they want the above example to render instead as:

1. My title
1.1 My header
1.2 page1 title

I can get close to what they want with the following:

My title
========

.. toctree::

   page1

My header
---------

however, this results in an incorrect ordering of the sections (which becomes a problem with latex builds etc).

I wonder if this pattern is possible right now and I am missing something? Otherwise, I'm curious what folks think about adding a keyword argument for toctree like level: 2 that would tell Sphinx what level it should use for the toctree titles.

I'm not sure if I'm explaining this well or not, happy to try and clarify if it helps!

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

Start with the toctree directive and reproduce the issue's reStructuredText example in Sphinx, including a LaTeX build to observe the ordering problem. Define how a requested level should place toctree pages beside the index page's top-level headers, then verify both hierarchy and ordering for the existing and new forms.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.