Sphinx 中是否有标准或最佳实践来为复合 Python 数据类型提供更准确的规范？例如，我有一个函数返回一个映射dict并正在使用样式。我应该做类似的事情：strstrnumpydoc
Returns
-------
out : dict of str to str
或者可能dict of str: str？
对于已知内容类型的列表，我注意到 NumPy 使用格式
foo : list of int
对于这个常见用例，是否有标准或最佳实践可以遵循？
问问题
724 次
2 回答
0
我不确定这是否是最佳做法，但我通常会做类似:returns: dict( str=str ). 我认为这确实是最适合您和您的项目的方法。如果你使用 PyCharm 之类的东西，它会为你的文档字符串推荐“最佳”选项，但它会慢慢停止推荐东西，因为它注意到你做的事情不同。像 PEP8 这样的东西更像是指导方针（试图在这里做我最好的加勒比海盗印象），而不是硬性规定的规则。最重要的是能不能读懂。
一个非常好的灵感来源是 Python 自己的文档。如果您正在浏览它并注意到一个漂亮的页面，请查看左侧栏并单击“显示源”，然后复制该样式......我一直这样做:)
于 2015-04-10T20:48:50.490 回答
0
老问题，但在搜索该信息时仍然是热门问题之一。
经过更多搜索后，我在Sphinx 文档中找到了这个：
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]
于 2020-11-12T17:16:55.540 回答