Добавление файлов в подпапках в документацию sphinx (sphinxcontrib-matlabdomain)

Question

У меня есть каталог, содержащий различные папки, в каждой из которых есть исходные файлы Matlab. Некоторые из этих папок имеют подпапки, содержащие исходные файлы Matlab.

Как создать дерево оглавления с помощью Sphinx для вложенных папок?

Например, когда Main-Directory содержит conf.py, index.rst, а также moduleslist.rst вместе со следующей структурой папок:

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

с этим index.rst файл:

.. toctree::
    :maxdepth: 1

    moduleslist

и это moduleslist.rst файл:

.. toctree::
    :maxdepth: 2

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

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

Но это не включает в себя подпапку Folder2.1 и файлы в нем. Я пробовал добавлять Folder2/index в index.rstс Folder2/index.rst содержащий автомодуль для Folder2.1, который не включал документацию ghi.m,

Как мне заставить Sphinx отображать вложенные подпапки в его дереве оглавления?

Answer 1

Я начал использовать Sphinx и столкнулся с этой проблемой в документации в целом (не относится к функции autodoc). Вот как я заставил его работать и намного лучше контролировать, как строится дерево.

Рассматривайте каждую папку как отдельную группу. Таким образом, в корневом каталоге Sphinx у вас будет файл index.rst, который будет выглядеть так:

.. toctree::
    :maxdepth: 1

    Folder1/index
    Folder2/index

Я использую maxdepth: 1 так, чтобы это только перечислило название основной группы.

Под Folder1 и Folder2 вам нужно будет добавить дополнительные index.rst файлы:

#Folder1/index.rst

.. toctree::
    :maxdepth: 2

    abc.m
    def.m

#Folder2/index.rst

.. toctree::
    :maxdepth: 2

    Folder2.1/index
    jkl.m

В качестве примечания я настроил свои индексные страницы так, чтобы они либо имели только групповые списки (maxdepth: 1) или подробные списки страниц (maxdepth: 2) - Я уверен, что есть способ сделать папку / индекс на глубине 1 и файлы на глубине 2.

Затем в течение Folder2.1 вам понадобится ваш третий индекс:

#Folder2.1/index.rst

.. toctree::
    :maxdepth: 2

    ghi.m

Вот Сфинкс Документы на Вложенныхtoctree и это было не так ясно. Очевидно, вам понадобится autodoc код для более сложных / глубоких древовидных структур.