sphinx-doc / sphinx-doc/sphinx
Allow to specify toctree pages as direct-children of parent page
Nobody has claimed this yet.
- 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
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
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