我正在整理我的python代码文档,决定使用sphinx-doc,因为它看起来不错,我喜欢用这样的标签引用其他类和方法:
:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function
我试着弄清楚如何在函数中记录参数名,这样如果我有一个函数:
def do_this(parameter1, parameter2):
"""
I can describe do_this.
:something?:`parameter1` And then describe the parameter.
"""
这方面的最佳实践是什么?
更新日期:
正确的语法为:
def do_this(parameter1, parameter2):
"""
I can describe do_this.
:something parameter1: And then describe the variable
"""
3条答案
按热度按时间fdx2calv1#
通常"函数变量"称为参数;).
它记录在这里:www.example.comhttp://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#signatures
答案是
:param ________
dhxwm5r42#
将此答案添加到合并选项中:
pydoc是基本的,没有特殊格式
epydoc使用格式“@param var:”
Doxygen面向更广泛的语言
Sphinx使用":param type var:“格式。另请参阅更多示例。这用于创建Python 3.5 documentation。
a0zr77ik3#
如何记录类型
还值得注意的是参数类型的旧语法
:type parameter2: MyClass
,也在www.example.com上有文档https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#signatures但是使用Python 3
typing
,我们可以:main.py
build.sh
conf.py
index.rst
requirements.txt
out/index.html
上的输出:注意它是如何将参数类型正确地链接到类
MyClass
的文档的。