Sphinx Python 3 类型最小可运行示例
为了更加具体化其他答案所说的内容：
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,
'show-inheritance': True,
}
autodoc_typehints = "description"
index.rst
.. automodule:: main
main.py
class MyClass:
"""
This class does that.
"""
def __init__(self, i):
self.i = i
def do_this(parameter1: int, parameter2: MyClass) -> int:
"""
This function does this.
:param parameter1: my favorite int
:param parameter2: my favorite class
:return: what it returns
"""
return parameter1 + parameter2.i
requirements.txt
Sphinx==6.1.3
输出到 out/index.html：
如果我们移除：
autodoc_typehints = "description"
在函数签名中显示打字类型：
预输入等效
以下代码将产生与使用autodoc_typehints = "description"版本相同的输出，但会稍微重复一些参数名称：
def do_this(parameter1, parameter2):
"""
This function does this.
:param parameter1: my favorite int
:type parameter1: int
:param parameter2: my favorite class
:type parameter2: MyClass
:return: what it returns
:rtype: int
"""
return parameter1 + parameter2.i
梦想：参数文档字符串
我们不得不为每个:param argumentname:重新输入参数名称，这是很糟糕的。目前似乎没有一个好的解决方案。以下是一些未来可能解决这个问题的方法：
Sphinx可以为参数添加#:文档注释。如How to show instance attributes in sphinx doc?所述，该Sphinx扩展已经适用于实例属性。
class MyClass:
def __init__(self, par1: int):
self.var1: int = par1
那么为什么不给我们：
def do_this(
parameter1: int,
parameter2: MyClass
) -> int:
Python终于可以原生支持参数文档字符串了！
def do_this(
parameter1: int,
"""
my favorite int
"""
parameter2: MyClass
"""
my favorite class
"""
) -> int:
TODO 找到这些功能请求的需求！
同样的需求也在此处提及：https://dev59.com/MWox5IYBdhLWcg3weUCe#39581355
其他有用的打字相关事项
已在Python 3.10、Ubuntu 22.10上测试。
