Сфинкс - автоданные показывают str .__ doc__ - PullRequest
Новая
       18

Сфинкс - автоданные показывают str .__ doc__

4 голосов
/ 06 января 2012

Я пытаюсь документировать свой код на Python с помощью Sphinx, но обнаружил проблему с документированием некоторых данных, созданных с помощью exec;У меня есть таблица с именами и значениями, которые мне нужно создать.

Итак, в своем коде я написал что-то вроде: 

my_vars = [{'name': 'var1', 'value': 'first'},
           {'name': 'var2', 'value': 'second'}]

for var in my_vars:
    exec("{var[name]} = '{var[value]}'".format(var=var))

Проблема в Sphinx: поскольку я хотел бы сохранить только исходный код, который я использовал autodata, соответствующие строкииз моего .rst файла: 

.. autodata:: mymodule.var1

.. autodata:: mymodule.var2

, который при сборке дал мне это: 

mymodule.var1 = 'first'
    str(string[, encoding[, errors]]) -> str

    Create a new string object from the given encoded string.
    encoding defaults to the current default string encoding.
    errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

mymodule.var2 = 'second'
    str(string[, encoding[, errors]]) -> str

    Create a new string object from the given encoded string.
    encoding defaults to the current default string encoding.
    errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

Я думаю, что autodata идет в var1.__doc__ для строки документа и там нашел str.__doc__ (это сообщение показывалось ранее).

Я действительно не знаю, что делать, и я ищу способ не показывать эту уродливую строку документа (но все еще поддерживаю mymodule.var1 = 'first').

Или, может быть, даже лучший способ показать мой собственный документ, например: var1 is this. (но я не знаю, где его разместить).

Ответы [ 3 ]

3 голосов
/ 07 января 2012

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

mymodule.py: 

""" 
This module is...

Module variables:

* var1: var1 doc
* var2: var2 doc
"""

my_vars = [{'name': 'var1', 'value': 'first'},
           {'name': 'var2', 'value': 'second'}]

for var in my_vars:
    exec("{var[name]} = '{var[value]}'".format(var=var))

...
...

Вы также можете использовать информационные поля : 

"""

:var var1: var1 doc
:var var2: var2 doc
"""

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

Обновление: продолжение комментариев о str подклассах. Это работает для вас? 

from collections import UserString   

my_vars = [{'name': 'var1', 'value': 'first', "doc": "var1 docstring"},
           {'name': 'var2', 'value': 'second', "doc": "var2 docstring"}]

for var in my_vars:
    code = """\
{0} = UserString('{1}')
{0}.__doc__ = '{2}'""".format(var["name"], var["value"], var["doc"])
    exec(code)
0 голосов
/ 10 июня 2012

Я понял, как вы можете это исправить. Напишите что-нибудь вроде этого: 

x = 55
"""
x is varibble lala
"""

Используйте директиву автомодуля, и Sphinx создаст для вас документы.

0 голосов
/ 07 января 2012

Учитывая, что в этом случае трудно sphinx.ext.autodoc сгенерировать желаемую строку документации, потому что:

  • код оценивается через exec
  • значения могут не позволить вам перезаписать строку документации

Вы рассматривали возможность жесткого кодирования документации в самом документе rst? 

.. data:: mymodule.var1

   var1 is this

.. data:: mymodule.var2

   var2 is that
...