我正在尝试使用Sphinx记录我的python代码,但是我发现了一个问题,记录了一些用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’.
我认为自动数据会查找var1.__doc__
的文档字符串,并找到str.__doc__
(这是之前显示的消息)。
我真的不知道该怎么做,我正在寻找一种不显示丑陋的文档字符串(但仍然保持mymodule.var1 = 'first'
)的方法。
或者更好的方式来展示我自己的文档,例如:var1 is this.
(但我不知道在哪里放置它)。
答案 0 :(得分:3)
我的建议是:记录模块docstring中的变量,而不是试图从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))
...
...
您也可以使用info fields:
"""
: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)
答案 1 :(得分:0)
鉴于在这种情况下很难让sphinx.ext.autodoc
生成所需的文档字符串,因为:
exec
您是否考虑过对rst
文档中的文档进行硬编码?
.. data:: mymodule.var1
var1 is this
.. data:: mymodule.var2
var2 is that
答案 2 :(得分:0)
我意识到你怎么能解决它。 写这样的smth:
x = 55 """ x is varibble lala """
使用automodule指令,Sphinx将为您制作文档。