用于复合数据类型的Sphinx文档

Question

Sphinx中是否有标准或最佳实践来为复合Python数据类型提供更准确的规范？例如，我有一个函数，该函数返回dict映射str到str并正在使用numpydoc样式。我应该做类似的事情：

Returns
-------
out : dict of str to str

或可能是dict of str: str？

对于知道内容类型的列表，我注意到NumPy使用了格式

foo : list of int

此常见用例是否遵循标准或最佳做法？

Answer 1

我不确定这是否是最佳做法，但我通常会执行:returns: dict( str=str )之类的操作。我认为这才是最适合您和您的项目的。如果您使用类似PyCharm的工具，它将为您的文档字符串推荐“最佳”选项，但由于它会发现您的做法有所不同，因此它会慢慢停止推荐内容。像PEP8这样的东西更像是准则（试图在这里尽我所能给加勒比海盗带来最好的印象），而不是硬性规定。最重要的是您是否可以阅读它。

一个非常好的灵感来源是Python自己的文档。如果您正在浏览它，并且注意到页面漂亮，请在左侧栏上查看并单击Show Source，然后直接复制该样式...我一直都在这样做：）