Sphinx - 自动数据显示 str.__doc__

Question

我正在尝试使用 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. （但我不知道把它放在哪里）。

Answer 1

我的建议是：在模块文档字符串中记录变量，而不是尝试从 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)

Answer 2

鉴于在这种情况下很难让 sphinx.ext.autodoc 生成所需的文档字符串，因为：

• 代码是通过 exec 评估的，
• 这些值可能不允许您覆盖文档字符串

您是否考虑过在 rst 文档本身中对文档进行硬编码？

.. data:: mymodule.var1

   var1 is this

.. data:: mymodule.var2

   var2 is that

Answer 3

我意识到你该如何解决它。
像这样编写：

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

使用 automodule 指令，Sphinx 将为您制作文档。