Sphinx 中是否有标准或最佳实践来为复合 Python 数据类型提供更准确的规范？例如，我有一个函数返回一个 dict 映射 str 到 str 并使用 numpydoc 样式。我应该这样做：
Returns
-------
out : dict of str to str
或者可能是dict of str: str？
对于已知内容类型的列表，我注意到 NumPy 使用该格式
foo : list of int
对于这种常见用例，是否有可遵循的标准或最佳实践？
【问题讨论】：
标签： python python-sphinx numpydoc
我不确定这是否是最佳做法，但我通常会执行:returns: dict( str=str ) 之类的操作。我认为这确实是最适合您和您的项目的方法。如果你使用 PyCharm 之类的东西，它会为你的文档字符串推荐“最佳”选项，但它会慢慢停止推荐，因为它注意到你做的事情不同。像 PEP8 这样的东西更像是指导方针（试图在这里做我最好的加勒比海盗印象），而不是硬性规定的规则。最重要的是你能不能看懂。
一个非常好的灵感来源是 Python 自己的文档。如果您正在浏览它并注意到一个漂亮的页面，请查看左侧栏并单击显示源代码，然后复制该样式...我一直这样做:)
【讨论】：
老问题，但在搜索该信息时仍然是热门问题之一。
经过更多搜索，我在Sphinx docs找到了这个：
New in version 1.5.
Container types such as lists and dictionaries can be linked automatically using the
following syntax:
:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]
【讨论】：