如何在 PyCharm 中选择 reST 文档字符串存根的格式？

Question

在 JetBrain's example for docstring in Pycharm 中提到：

Note that for reStructuredText it's possible to specify types in two formats:

:param param_type param_name: parameter description (type description is on the same line as the parameter description).

:type param_name: param_type (type description is on a separate line)

我想让我的 pycharm 自动生成第二个变体，而不是第一个？目前，它甚至没有添加类型

def foo(a: str, b: int = 1) -> str:
    """

    :param a: 
    :param b: 
    :return: 
    """
    return a + str(b)

一个相关的问题是：How to customize docstring generation in pycharm and share the template through git?

Answer 1

目前，尽管文档提到了这两种格式，但似乎无法在这两种样式之间切换。 https://youtrack.jetbrains.com/issue/PY-12327

您可以通过选中以下选项来启用第二种样式（我认为您想要）： Editor - General - Smart Keys - Python 检查 Insert type placeholders in the documentation comment stub。（或使用设置搜索并搜索 comment stub）

非常不直观，许多人一直在请求改进 PyCharm 中的此功能。理想情况下，您希望能够提供这种样式的自定义 sphinx.mustache 文档字符串模板：

{{! Sphinx Docstring Template }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}

{{#args}}
:param {{var}}: {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
:param {{var}}: {{descriptionPlaceholder}}
{{/kwargs}}
{{#exceptions}}
:raises {{type}}: {{descriptionPlaceholder}}
{{/exceptions}}
{{#returns}}
:return: {{descriptionPlaceholder}}
{{/returns}}
{{#yields}}
:yield: {{descriptionPlaceholder}}
{{/yields}}

（示例取自此处 https://github.com/executablebooks/markdown-it-py/blob/master/docstring.fmt.mustache）

但同样，PyCharm 目前不支持 - 请随时对链接的问题发表评论和投票，也许它会得到一些关注。

如何在 PyCharm 中选择 reST 文档字符串存根的格式？

How to choose format of reST docstring stubs in PyCharm?

python

restructuredtext

docstring

pycharm