如何使用 Sphinx 记录 Python 函数参数？

Question

我正在尝试清理我的 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
   """

Answer 1

通常“函数变量”称为参数；）。

此处记录：http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#signatures

答案是

:param ________

编辑免责声明：我从未使用过或听说过狮身人面像......这篇文章主要是“要搜索什么词”。希望它有所帮助。

Answer 2

添加此答案以合并选项：

pydoc 是基本的，没有特殊格式

epydoc 使用格式 '@param var:'

Doxygen 面向更大范围的语言

Sphinx 使用格式 ':param type var:'。另请参阅更多示例。这用于创建Python 3.5 文档.

Answer 3

如何记录类型

同样值得注意的是参数类型的旧语法

:type parameter2: MyClass

，也记录在https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#signatures

但是使用 Python 3

typing

我们可以：

main.py

#!/usr/bin/env python

class MyClass:
    """
    This class does that.
    """
    def __init__(self, i):
        self.i = i

def do_this(parameter1: int, parameter2: MyClass):
   """
   This function does this.

   :param parameter1: my favorite int
   :param parameter2: my favorite class
   """
   return parameter1 + parameter2.i

build.sh

sphinx-build . out

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))
extensions = [ 'sphinx.ext.autodoc' ]
autodoc_default_options = {
    'members': True,
}

index.rst

.. automodule:: main

requirements.txt

Sphinx==6.1.3

out/index.html

上的输出：

注意它如何正确地将参数类型链接到类的文档

MyClass

.