Create Sphinx nested TOC to link to a new page

Question

I'm trying to create a single entry on the main toctree with three nested entries that each link to a page (because our main TOC is already quite long). The structure is like this:

- Layers
    + Using Layers
    + Layer Arguments
    + Layers List

Layers is layers.rst and Using Layers is a heading in layers.rst. I created two more headings in layers.rst for Layer Arguments and Layers List because I want them to be on the same level. I created a toctree under the Layers Arguments heading, and a second one under Layers List so when you click on them it brings you to the TOC under each heading.

When you click Layer Arguments/Layers List I want it to go to the top of layer_args.rst/layers_list.rst, not to the heading in layers.rst. Is it possible to create a nested toctree that links to files in the sidebar?

Edit: Example

index.rst

<some headings and text>

.. toctree::
   :maxdepth: 2
   :caption: Layers

   layers

layers.rst

.. _using-layers:

------------------------------------------------
Using Layers
------------------------------------------------

<text>

------------------------------------------------
Layer Arguments
------------------------------------------------

.. toctree::
   :maxdepth: 2

   Layer Arguments <layers/layer_args>

------------------------------------------------
Layers List
------------------------------------------------

.. toctree::
   :maxdepth: 2

   I/O Layers <layers/io_layers>
   Operator Layers <layers/operator_layers>
   Transform Layers <layers/transform_layers>
   .
   .
   .

layers/io_layers.rst

layers/operator_layers.rst

layers/transform_layers.rst

Answer 1

I would move the file layers.rst to layers/index.rst, and adjust paths accordingly. Thus your directory structure and navigation structure align with one another.

docs/index.rst

.. toctree::
   :maxdepth: 2
   :caption: LBANN Layers

   layers/index

docs/layers/index.rst

------------------------------------------------
Layer Arguments
------------------------------------------------

.. toctree::
   :maxdepth: 2

   Layer Arguments <layer_args>

------------------------------------------------
LBANN Layers List
------------------------------------------------

.. toctree::
   :maxdepth: 2

   I/O Layers <io_layers>
   Operator Layers <operator_layers>
   Transform Layers <transform_layers>