:synopsis: не работает в автомодуле Sphinx

Question

Я использую Sphinx, он мне очень нравится, но он не подберет краткий обзор модуля. Нет ошибок или чего-то еще, просто... ничего. Это модуль, который я пытаюсь автодокументы:

# vim: set fileencoding=utf-8 :
"""
.. module:: CONF
   :synopsis: Configuration module, tells where data files are.

.. moduleauthor:: Mr Anderson <[e-mail]>
"""

Это директива Sphinx в индексном файле ReST:

.. automodule:: CONF
   :synopsis:

Я получаю от Сфинкса множество других замечательных вещей, так что для меня это не сломано. Единственная подозрительная вещь, которую я получаю: SEVERE: Duplicate ID: "module-CONF", Некоторый поиск в Google заставил меня поверить, что эта ошибка вполне "нормальная"?

Answer 1

Я думаю, что вы используете :synopsis: вариант неправильно на automodule директивы. Вы используете эту опцию то же самое на automodule как вы делаете на module, Другими словами, вы должны указать синопсис в строке с :synopsis: вариант по любой из директив.

Как правило, вы используете либо module директива или automodule директива, а не оба. Это также, почему вы получаете предупреждение о дубликатах. Это прискорбно, потому что, насколько мне удалось найти, нет способа включить краткий обзор в строку документации, если вы используете automodule

Поэтому, если вы хотите использовать автомодуль и краткий обзор без предупреждения, я думаю, вы должны сделать это:

.. automodule:: CONF
   :synopsis: Configuration module, tells where data files are.

А потом избавиться от `.. module:: директива в самом файле src.

Я думаю, что у вас все получится, но вы получите это предупреждение. Кроме того, вы должны удалить :synopsis: вариант из automodule: без фактической строки синопсиса, следующей за ней, это не принесет вам пользы и может привести к "пустому" синопсису.

Answer 2

Не уверен, действительно ли это отвечает на ваш вопрос, но, возможно, вы ищете "неправильное" место, чтобы найти синопсис. ("неправильно", потому что вполне разумно ожидать, что automodule директива есть). Из документации по разметке модуля (выделено мое):

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

Итак, для строки комментария модуля:

"""

.. module:: CONF
  :synopsis: Configuration module, tells where data files are.
    continuation possible here... (though goes against the point of synopses...)
  :platform: Windows

"""

синопсис выходит в индекс модуля - что-то вроде

с

Модуль конфигурации CONF (Windows) ,....

В качестве альтернативы для строки комментария модуля (примечание отступа):

"""

:synopsis: Configuration module, tells where data files are to.

"""

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

Как несколько неприятный обходной путь, вы могли бы объединить эти два :synopsis: декларации, хотя ясно, что это не очень ремонтопригодно.

Answer 3

Следуя решению Bonlenfum, вот (еще больше) краткий пример, который печатает директивы модуля как в модульном индексе, так и в строках документа:

"""
.. module:: CONF
  :synopsis: written in module index..................................newlines are
    automatically handled (still, mind the spacing)
  :platform: Windows

.. moduleauthor:: Mr Anderson <[e-mail]>

:synopsis: this is written in the docstrings..........................newlines are handled
  automatically handled (mind spacing) or I can force newlines with \n
  a newline character.
"""

Я добавил "...", чтобы добавить пробел так, чтобы строка была достаточно длинной для автоматического продолжения сфинкса на новой строке. Автор модуля отображается только в строках документа (не в индексе).

это хорошо работает с Sphinx 1.2 и прочитайте тему документации