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

[choldgraf]

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!

[cgay]

In Sphinx 4.2.0 I don't see the behavior described at the top of the first comment at all. No matter where I put the toctree directive in my top-level index.rst page, none of the headers in index.rst appear in the ToC at all; only the headers in the files listed in the toctree directive's contents show up in the ToC.

For example, given this index.rst file,

$ cat index.rst 
.. abc documentation master file, created by
   sphinx-quickstart on Sun Oct 10 23:06:59 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to abc's documentation!
===============================

Dog
===

My dog has fleas.

.. toctree::

   foo
   bar

Cat
---

My cat has paws.

CatSub
~~~~~~

This is a cat subheader.

CatSubSub
.........

This is a cat subsubheader.

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

The sidebar looks like this:

abc                  // project name
Navigation           // boilerplate?
1. Foo               // Title in foo.rst
2. Bar               // Title in bar.rst
QuickSearch
_________

Specifically, none of the headers in index.rst are in the sidebar, no matter where I place the toctree directive.

Sphinx 4.2.0, Alabaster theme. Hopefully this isn't just a n00b mistake on my part. My test site is attached. site.tar.gz

[jwodder]

Although the original post suggests HTML, I am experiencing this phenomenon when building a PDF of my docs via LaTeX using Sphinx 5.0.1. The pages listed in the toctree are treated as sub-sections of whichever section in index.rst the directive occurs under rather than as siblings, and I cannot see a way to get what I want.