Пропустить (или отформатировать) значение переменной при документировании с помощью Sphinx

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

Я попытался исключить переменную из директивы automodule и добавить ее так:

.. automodule:: foo.bar
   :members:
   :exclude-members: longstuff

   .. py:data:: longstuff

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

Как я могу одновременно сохранить строку документации и избавиться от значения (или красиво отформатировать его)?


python documentation python-sphinx autodoc
person Lev Levitsky    schedule 02.06.2012    source источник

Ответы (1)


arrow_upward
5
arrow_downward

Не существует простой настройки конфигурации для пропуска значений переменных уровня модуля в выходных данных. Но вы можете сделать это, изменив метод DataDocumenter.add_directive_header() в autodoc.py< /а>. Ключевая линия в этом методе

self.add_line(u'   :annotation: = ' + objrepr, '<autodoc>')

где objrepr — это значение.

У меня работает следующий патч обезьяны, добавленный в conf.py:

from sphinx.ext.autodoc import ModuleLevelDocumenter, DataDocumenter

def add_directive_header(self, sig):
    ModuleLevelDocumenter.add_directive_header(self, sig)
    # Rest of original method ignored

DataDocumenter.add_directive_header = add_directive_header
person mzjn    schedule 03.06.2012
comment
С другой стороны, изменения не произойдут, если я просто переделаю страницы, а только если я что-то изменю в исходном коде страницы. Это случается довольно часто и очень раздражает. Это обычное дело? Как проще всего обеспечить применение изменений? Похоже, он предполагает, что никаких изменений не требуется, если исходный код не поврежден, что неверно. - person Lev Levitsky; 03.06.2012
comment
Я не уверен, что понимаю. Я использую make clean html, чтобы убедиться, что все переделано с нуля. - person mzjn; 03.06.2012
comment
Думаю, это то, что мне нужно. Извините за глупый вопрос, я просто редко использую make, кроме документов Sphinx :) - person Lev Levitsky; 03.06.2012
comment
Работает на меня. Обратите внимание: если вы хотите, чтобы это применялось только к определенным символам, вам придется написать более сложную функцию, которая проверяет self.name и делегирует исходный метод, если имя не совпадает. - person Christopher Barber; 26.08.2019