PyCharm Quick Documentation Sphinx Support

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.


is a syntactic sugar for


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.


  1. Multiple Supported Types

    :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)

  2. 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.


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


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

    A deer, a female deer
    A drop of golden sun
    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


Sphinx defines several roles for the Python domain:

  1. :py:mod: for modules
  2. :py:func: for functions
  3. :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


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

Linking to an Exception


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

Linking to a URL
`Link Name <>`_

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


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


Linking to an RFC


Other supported Restructured Text features

  1. Headers
  2. Sections
  3. Literal blocks
  4. Images

Restructured Text features that aren’t supported:

As of Dec 2019

  1. Line blocks
  2. Block quotes
  3. Doctest blocks
  4. Tables
    • They kind of work because of the headers, but they’re not great.
  5. Field lists
  6. Footnotes
    • PyCharm tries to make them into external links which fails.
  7. Sidebars
  8. Line Block