Структурирование Sphinx документации

Question

Я начал документировать проект Python, используя Sphinx. Я использую его впервые - я привык к инструментам, которые работают с JavaDoc-подобным синтаксисом, и у меня есть некоторые сомнения.

Поскольку я хочу, чтобы документация появлялась рядом с кодом, я использую директивы .. automodule::, .. autoclass:: и .. automethod::. Итак, структура моей документации следующая: index.rst содержит оглавление и

.. automodule:: my_main_package

, а затем на верхнем уровне __init__.py содержатся такие директивы, как

.. automodule:: some_subpackage

для каждого подпакета и т. Д. Наконец, каждый модуль содержит директивы

.. autoclass:: some_class
    :members:

для каждого класса в модуле.

В основном это работает, но я получаю одностраничную документацию, с которой немного странно работать.

Как мне организовать свою документацию, чтобы получить дерево файлов с гиперссылками? То есть основной пакет должен содержать собственную документацию и ссылки на каждый из его подпакетов и т. Д., Пока каждый модуль не имеет своей собственной страницы.

Answer 1

Я нашел этот скрипт автопакета из комментария здесь . Он генерирует необходимые файлы .rst в соответствии со структурой ваших пакетов.

примечание: я все еще чувствую, что мне чего-то не хватает, поскольку я не могу поверить, что такой инструмент, как Sphinx, известный как самый продвинутый инструмент для документирования Python, не хватает функциональности для создания базовой документации API. Поэтому я оставлю вопрос открытым некоторое время, прежде чем принять собственный ответ.

Answer 2

Даже я не эксперт в этом, но я думаю, что могу ответить на то, что вы спросили здесь (об организации документации / первых файлов).

Ключ, который вы можете здесь упустить, - вместо использования вызовов autoclass / automodule / automethod в том же самом верхнем уровне TOC s-файл первого уровня, этот файл верхнего уровня должен содержать ссылки на другие файлы первого типа, содержащие эти вызовы.

предположим, что у вас есть все первые файлы внутри doc dir (и его подкаталоги),

Table of contents
=================
The contents of the docs are:

.. toctree::
    :maxdepth: 1

    module_1/index
    module_2/index

в директории, содержащей этот верхний уровень index.rst, у вас будут подкаталоги с именами module_1 и module_2. Они будут иметь index.rst (имя только для конкретного примера), который в свою очередь будет содержать .. automodule::, .. autoclass:: и .. automethod::. Может содержать что-то вроде

:mod:`module_1`
---------------

..automodule:: module_1
    :show-inheritance:

.. autoclass:: module_1.MyClass

Конечно, это не стандартный или идеальный способ, я предлагаю это, потому что он аккуратнее. в качестве альтернативы вы можете иметь все первые файлы с документами модуля / класса / метода в том же каталоге, что и index.rst верхнего уровня со структурой

Table of contents
=================
The contents of the docs are:

.. toctree::
    :maxdepth: 1

    module_1
    module_2

и тот же каталог будет содержать doc-файлы module_1.rst, module_2.rst и т. Д. Пути: относительно к файлу config.py.

Answer 3

Я ни в коем случае не эксперт по Sphinx, но из прочтения документации кажется, что вы можете включить TOC-деревья в подкаталоги. Страница дерева оглавления также дает некоторую информацию о путях внутри дерева;Вы экспериментировали с использованием путей в дереве?