Получить "плоский" вывод элемента для автомодуля sphinx - PullRequest
Новая
       4

Получить "плоский" вывод элемента для автомодуля sphinx

15 голосов
/ 13 ноября 2011

Я использую расширение Sphinx autodoc для документирования модуля, и я хотел бы получить flat список членов модуля в выходных данных документации.

Я пытался использовать следующее: 

.. automodule:: modname
   :members:

Однако есть две проблемы с этим:

  1. Включает строку документации модуля, которую я не хочу здесь.

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

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

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

Обновление: По крайней мере, я нашел обходной путь для второй части: установите add_module_names=False в conf.py. Это глобальная настройка, поэтому она не отвечает на мой первоначальный вопрос.

1 Ответ

4 голосов
/ 07 декабря 2011

Глядя на этот ответ на аналогичный вопрос, я обнаружил, что вы можете использовать событие autodoc-process-docstring для удаления строк документации из модулей, добавляя следующий код к вашему conf.py 

def skip_modules_docstring(app, what, name, obj, options, lines):
    if what == 'module':
        del lines[:]

def setup(app):
    app.connect('autodoc-process-docstring', skip_modules_docstring)

Обратите внимание, что оператор del необходим, потому что, согласно документации, изменение lines должно произойти на месте (если вы создаете новый объект, оно не работает).

Наконец, вы также можете использовать name, чтобы отфильтровать строки документов только нескольких модулей, оставив их у других.

...