Autosummary с toctree не создает документацию для методов

Я использую sphinx с расширением numpydoc и автосуммированием. После некоторых экспериментов я добавил следующие параметры в свой файл conf.py.

autosummary_generate = True
numpydoc_show_class_members = False

Это дает мне новый файл для каждого класса, на который ссылаются, как показано ниже, а также создает сводную таблицу всех атрибутов и методов.

.. autosummary::
   :toctree: generated/
   :nosignatures:

   MyClass

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


python python-sphinx autodoc toctree numpydoc
person kesmit    schedule 09.07.2016    source источник
comment
1) Просто нет ссылок или файлы, которые должны быть целью ссылки, отсутствуют? 2) Вместо сводной таблицы методов я ожидал увидеть сводную таблицу классов, перечисленных в директиве autosummary. Я что-то неправильно понимаю?   -  person mzjn    schedule 09.07.2016
comment
Он создает файл для MyClass, в котором есть директива автокласса со всеми атрибутами и методами, но на этом все заканчивается. Результирующий HTML-файл содержит строку документа класса и сводные таблицы атрибутов и методов, но для этих методов документация не создается. Кажется, что в этом файле должен быть еще один :toctree: для создания полного дерева.   -  person kesmit    schedule 09.07.2016
comment
См. мой комментарий от 31 января 2013 г. в 20:01 в этом ответе: stackoverflow.com/a/14621772/407651. Это может помочь.   -  person mzjn    schedule 09.07.2016
comment
Хорошо, это помогает. Я использовал autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance', 'inherited-members'] в своем conf.py, и я намного ближе к тому, что мне нужно. Поэтому я думаю, что если я хочу просто использовать сгенерированную документацию для класса, я могу использовать autosummary с toctree, и вся документация будет помещена в один файл. Однако, если я хочу разделить документацию по методу на отдельные файлы для большого класса, тогда мне придется вручную создать первый файл класса с директивой автосуммирования и сгенерировать файлы-заглушки для методов, правильно?   -  person kesmit    schedule 09.07.2016
comment
Я только что заметил, что Pandas делает это именно так. У них есть api.rst, написанный от руки и явно ссылающийся на методы класса. Затем они используют :toctree: для создания заглушек.   -  person kesmit    schedule 09.07.2016

Ответы (1)


arrow_upward
1
arrow_downward

Во-первых, убедитесь, что в вашем файле conf.py строки sphinx.ext.autodoc и sphinx.ext.autosummary находятся в списке extensions.

Во-вторых, вы можете либо вручную создать файл с именем mymodule.MyClass.rst внутри каталога generate/, что может быть примерно так:

mymodule.MyClass
================

.. currentmodule:: mymodule

.. autoclass:: MyClass

или, если у вас много классов, вы можете автоматизировать это с помощью sphinx-autogen. Вы можете запустить его из терминала (с cd так же, как файл conf.py) как:

сфинкс-автоген *.rst

person Gerges    schedule 09.07.2016