How to choose format of reST docstring stubs in PyCharm?

Question

In JetBrain's example for docstring in Pycharm, it is mentioned that:

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)

I want to make my pycharm autogenerate the second variant, not the first one? Currently, it is even not even adding the type

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

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

a related question is: How to customize docstring generation in pycharm and share the template through git?

Answer 1

Currently, in spite of the documentation mentioning both formats, it appears it is not possible to switch between the two styles. https://youtrack.jetbrains.com/issue/PY-12327

You can enable the second style (which I think you want) by checking the following option: Editor - General - Smart Keys - Python check Insert type placeholders in the documentation comment stub. (or use the Settings search and search for comment stub)

Very unintuitive and many people have been requesting improvements to this functionality in PyCharm. Ideally, you'd want to be able to provide a custom sphinx.mustache docstring template of this style:

{{! 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}}

(example taken from here https://github.com/executablebooks/markdown-it-py/blob/master/docstring.fmt.mustache)

But again, that is currently not supported in PyCharm - feel free to comment and vote on the linked issue, and perhaps it gets some attention.