Document source code
Basics
PyCharm provides convenient features for creating documentation comments.
Documentation comments in your source code are available for the Code reference information and open for review on pressing Ctrl+Q.
Python documentation
Documentation comments can be created in accordance with the syntax, selected in the Python Integrated Tools page of the project settings (Ctrl+Alt+S), for example, reStructuredText or epytext.
If this feature applies to a function, PyCharm generates tags, depending on the selected docstring format, for example:
For reStructuredText:
:param
tags for each parameter declared in the function signature, and:return
tag.For epytext:
@param
tags for each parameter declared in the function signature, and@return
tag.
The tags in reStructuredText and epytext markup are highlighted accordingly.
If configured, the documentation comment stubs can be generated with type
and rtype
tags.
In the Python files, PyCharm recognizes the documentation comments represented as Python docstrings.
Before you start, make sure that the required docstring format, for example, epytext
or reStructuredText
, is selected in the Python Integrated Tools page of the Settings dialog.
Also note that PyCharm captures custom roles from conf.py. When configuring the directory that contains *.rst files, point to the directory with conf.py (Python Integrated Tools | Path to the directory with *.rst files).