如何在 PyCharm 中選擇 reST 文檔字符串存根的格式？

Question

在JetBrain 的 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)

一個相關的問題是： 如何在 pycharm 中自定義文檔字符串生成並通過 git 共享模板？

Answer 1

目前，盡管文檔中提到了這兩種格式，但似乎無法在兩種 styles 之間切換。 https://youtrack.jetbrains.com/issue/PY-12327

您可以通過選中以下選項來啟用第二種樣式（我認為您想要）： Editor - General - Smart Keys - Python check 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 目前不支持這一點 - 請隨時對鏈接問題發表評論和投票，也許它會引起一些關注。