Как мне избежать СЕРЬЕЗНЫХ предупреждений о повторяющихся идентификаторах для моих модулей autodoc'd в Sphinx?

Я использую rST / Sphinx для документирования моего Python, однако при создании он выдает предупреждения, такие как

...Code/doc/code.rst:3: SEVERE: Duplicate ID: "module-toast".

Мои исходные файлы Python задокументированы следующим образом:

#!/usr/bin/env python
'''
.. module:: toast
    :synopsis: Processes the blobs produced by :mod:`bread`.
'''
# my inline-rST documented code...

И файлы rST используют предоставленную autodoc директиву automodule для извлечения всех строк документации и документирования всех членов.

Toast
--------------------------------

.. automodule:: toast
    :members:

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


python python-sphinx autodoc
person Nick T    schedule 09.05.2013    source источник

Ответы (3)


arrow_upward
7
arrow_downward

Один из способов - использовать флаг :noindex:.

.. automodule:: toast
    :members:
    :noindex:

Затем в исходном коде вы можете использовать:

#!/usr/bin/env python
'''
.. module:: toast
    :synopsis: Processes the blobs produced by :mod:`bread`.
'''

СЕРЬЕЗНОГО предупреждения не будет, и сообщение в синопсисе появится в индексе модуля.

С другой стороны, :noindex: скроет модуль из индекса, если он не имеет .. module:: в исходном файле.

person simno    schedule 16.04.2014

arrow_upward
4
arrow_downward

Я не уверен, но считаю, что директива automodule сама по себе создаст директиву module. Затем, поскольку у вас уже есть один указанный, есть два, и, таким образом, вы получите дублирующееся сообщение с идентификатором.

Вы можете попробовать использовать директиву currentmodule в разметке вашего модуля вместо module. Похоже, что должно работать, хотя я признаю, что на самом деле не пробовал.

person Kevin Horn    schedule 15.05.2013
comment
currentmodule не принимает параметр :synopsis:, поэтому мне нужно переместить его в файл rST, тогда наличие директив module в источнике излишне. Мне интересно, возможно ли то, что я хочу (в настоящее время). :/ - person Nick T; 15.05.2013

arrow_upward
0
arrow_downward

:noindex: для automodule::, как написано simno, помогает, но предотвращает создание постоянных ссылок, и перекрестные ссылки (например, :func:) не будут работать. При добавлении :noindex: в module:: все работает должным образом, и вам не нужно использовать currentmodule.

person Mike    schedule 13.11.2017