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.
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.
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
List types can be specified by
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.
- This is a bullet list entry - This is another bullet list entry * Stars also work for bullet lists
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
doe A deer, a female deer ray A drop of golden sun me A name I call myself
will render properly.
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:
- :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
Linking to an Exception
Linking to a URL
`Link Name <http://someurl.com>`_
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
Restructured Text features that aren’t supported:
As of Dec 2019
- Line blocks
- Block quotes
- Doctest blocks