A list of the Restructured Text Syntax and Sphinx roles that PyCharm supports in docstrings.

Be sure to set “Docstring format” to “reStructuredText” in setttings.

Function Parameters:

def do_the_thing(the_thing, another_thing=None):
    """
    :param int the_thing: The thing's primary key
    :param another_thing: A second thing to also do specified by an int or a string
    :type another_thing: Union(int, string)

    :returns: A string with the outpu text form running the thing
    :rtype: str
    """

PyCharm will reorder the params in the documentation based on the order of the params in the function definition.

:param TYPE PARAM_NAME: DESCRIPTION

is a syntactic sugar for

:param PARAM_NAME: DESCRIPTION
:type PARAM_NAME: TYPE

and is functionally equivalent. The only exception is that in the shortcut the type can only be a single word. There is no syntactic sugar for specifying the return type and description on the same line.

Notes:

Multiple Supported Types
```
:type PARAM_NAME: TYPE_ONE or TYPE_TWO
:rtype: TYPE_ONE or TYPE_TWO
```
Can be used to list multiple types for a single parameter or return value. PyCharm will render this as Union(TYPE_ONE, TYPE_TWO)
List types

List types can be specified by list[str].

Default Role

The default restructured text role `surrounded by backticks` has no meaning in restructured text and can be used for anything. It can be a nice way to indicate that you are referring to a python variable, method, or parameter. PyCharm will italicize any text surrounded by backticks.

Transitions

PyCharm will render a horizontal line based on any four or more repeated punctuation characters

Lists:

Bullet list

- This is a bullet list entry
- This is another bullet list entry
* Stars also work for bullet lists

Enumerated List

Enumerated lists do not work. The following:

1. This is an enumerated list item
2. This is another
#. This item should be auto enumerated with the number '3'

renders as follows:

. This is an enumerated list item
. This is another
. This item should be auto enumerated with the number '3'

Something is happening because item is placed on a new line, but it does not render as a numbered list

Definition List

doe
    A deer, a female deer
ray
    A drop of golden sun
me
    A name I call myself

will render properly.

Option List

Useful for listing command line arguments. Must be at least two spaces between the definition and the description.

-a           this flag sets the variable a
-b filename  sets the variable b to the provided filename
--input=other  this will also render correctly
/V           even DOS/VMS-style options will work
-c           long descriptions can be
             broken over multiple lines

Linking:

Sphinx defines several roles for the Python domain:

:py:mod: for modules
:py:func: for functions
:py:data: for a module-level variable

The full list is available in the Sphinx docs

PyCharm supports a small selection with a slightly different syntax as listed below.

Linking to a class

:class:`SomeClassName`

This does not work inside of :param:, :type:, :return: descriptions.

Linking to an Exception

:exc:`SomeExceptionName`

This does not work inside of :param:, :type:, :return: descriptions.

Linking to a URL

http://someurl.com

`Link Name <http://someurl.com>`_

This does not work inside of :param:, :type:, :return: descriptions.

Math

Inline Math Formatting

PyCharm will italicize the following and make the powers into superscripts.

:math:`a^2 + b^2 = c^2

Other Semantic Markup

Sphinx has a selection of other miscellaneous roles documented here. The ones PyCharm supports in docstrings are listed below.

Linking to a PEP

:pep:`8`

Linking to an RFC

:rfc:`1462`

Other supported Restructured Text features

Restructured Text features that aren’t supported:

As of Dec 2019

Line blocks
Block quotes
Doctest blocks
Tables
- They kind of work because of the headers, but they’re not great.
Field lists
Footnotes
- PyCharm tries to make them into external links which fails.
Sidebars
Line Block