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?

Related [`Access m-files in a subfolder without permanently adding it to the path`](http://stackoverflow.com/questions/22013875/access-m-files-in-a-subfolder-without-permanently-adding-it-to-the-path). — Divakar, Nov 02 '15 at 20:49
@IKavanagh and others - another common oversight I see is forgetting to set `matlab_src_dir = os.path.abspath(os,path.join('path','to','mfiles'))` without this in `conf.py` Sphinx won't know where to find your MATLAB files. You can **not** just set the Python `sys.path` because that uses `importlib` to find **only** _Python_ files. — Mark Mikofski, Feb 23 '18 at 22:58
I wonder if this is related to how the parameter are documented in the comments? I wonder if the OP's MATLAB classes, class-methods and functions are documented using Sphinx markup? See [Sphinx Domains](http://www.sphinx-doc.org/en/stable/domains.html) for examples. Typically parameter documentation is given in comments after the first line of the object definition as `:param type arg: the description of the argument` — Mark Mikofski, Feb 23 '18 at 23:05

score 4 · Answer 1 · answered Jul 12 '18 at 03:44

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.

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

1 Answers1