Include another page’s ToC in Sphinx

Question

I have the following page at plugins/index.html:

Plugin Development
==================

.. toctree::
   :hidden:

   basics/index
   advanced/index


The Basics
----------

- :doc:`basics/gettingstarted`
- :doc:`basics/resources`
- :doc:`basics/i18n`


Advanced Topics
---------------

- :doc:`advanced/models`
- :doc:`advanced/controllers`
- :doc:`advanced/services`

plugin/basics/index.html and plugins/advanced/index.html contain their own toctree’s, which link to the same subpages listed in plugins/index.html. So what I’m wondering is, is there a way to just include those sub toctree’s, rather than manually listing the sub pages out like I’m doing?

I realize that I could just remove the :hidden: flag from the toctree, but the point is I want to keep Basic/Advanced topics in separate lists, with their own headings, intro paragraphs, etc.

Answer 1

You can list the entire directory contents like this (or various combinations of these directives):

.. toctree::
  :glob:
  :titlesonly:
  :maxdepth: 2

  **

or I think also like this (untested):

.. toctree::
  :glob:
  :titlesonly:
  :maxdepth: 2

  *
  basics/*
  advanced/*

However, I have found just manually listing things is often the best way to go. While the automatically generated TOCs are nice, they don't allow you much room in terms of formatting (for example, creating sub headings, and changing the order of pages etc).

In our documentation I have done pretty much the same thing you did in the initial question.