我正在学习如何使用 Sphinx 为我的代码创建文档。在我看到一些这样的例子之后:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
评论中使用什么语言让 Sphinx 理解并捕获它们?如果没有这种语法和逻辑,Sphinx 在我的代码中看不到注释,并且当我生成 HTML 时,模块是空的。
这里有一个例子:
最佳答案
您必须将注释与文档字符串(全称为“文档字符串”)区分开来。
见 PEP8 and notice docstrings apply only to模块、函数、类和方法。对于提到的对象,您可以申请 your_object.__doc__
以编程方式检索文档字符串;变量没有文档字符串。
关于你的例子:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
Sphinx 将检索的文档字符串中可以使用 3 种流行的语法:规范是在 Numpy 或 Google 风格之间进行选择(目前它们提供更好的可读性和功能,以及风格指南)。要使这些工作,您需要使用 Sphinx-Napoleon extension ,看看官方文档中的概述。
关于python-sphinx - Python 代码中注释和文档字符串的基本语法,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/62545038/