Adding files in subfolders to sphinx documentation (sphinxcontrib-matlabdomain)

Question

I have a directory containing various folders, with each of them having matlab source files in them. Some of these folders have sub-folders containing matlab source files.

How can I create a TOC tree with Sphinx to contain the sub-folders in a nested way?

For example, when Main-Directory contains conf.py, index.rst, and moduleslist.rst along with the following folder structure:

    Folder1
        abc.m
        def.m
    Folder2
        Folder2.1
            ghi.m
        jkl.m

with this index.rst file:

.. toctree::
    :maxdepth: 1

    moduleslist

and this moduleslist.rst file:

.. toctree::
    :maxdepth: 2

Folder1
=========
.. automodule:: Folder1
:members:

Folder2
=========
.. automodule:: Folder2
    :members:

But this does not include the sub-folder Folder2.1 and files in it. I have tried adding Folder2/index in index.rst, with the Folder2/index.rst containing the automodule for Folder2.1, which didn't include documentation of ghi.m.

How can I get Sphinx to show nested sub-folders in it's TOC tree?

Answer 1

I've started using Sphinx and have run into this problem on documentation in general (not specific to autodoc feature). This is how I got it to work and have much better control over how the tree is built.

Treat each folder as a separate group. So at the Sphinx root directory you'll have the index.rst file that will look like this:

.. toctree::
    :maxdepth: 1

    Folder1/index
    Folder2/index

I use the maxdepth: 1 so that it only list the major group name.

Under Folder1 and Folder2 you'll need to add additional index.rst files:

#Folder1/index.rst

.. toctree::
    :maxdepth: 2

    abc.m
    def.m

#Folder2/index.rst

.. toctree::
    :maxdepth: 2

    Folder2.1/index
    jkl.m

As a side note, I've setup my index pages so that they either have just group listings (maxdepth: 1) or detail page listings (maxdepth: 2) - I'm sure there is a way to make the folder/index at depth 1 and files at depth 2.

Then within Folder2.1 you'll need your third index:

#Folder2.1/index.rst

.. toctree::
    :maxdepth: 2

    ghi.m

Here is the Sphinx Docs on Nested toctree and it wasn't as clear. Obviously you'll need the autodoc code for more complicated/deep tree structures.