Documenting Source Code in PyCharm
In this part:
- Documenting Source Code in PyCharm
- Enabling Creation of Documentation Comments
- Creating Documentation Comments
- Generating Reference Documentation
- Type Hinting in PyCharm
- Using Docstrings to Specify Types
Basics
PyCharm provides convenient features for creating documentation comments.
Documentation comments in your source code are available for the Quick Documentation Lookup and open for review on pressing Ctrl+Q.
Documentation comments can be created in accordance with the RDoc or YARD syntax.
Documentation comments can be created in accordance with the syntax, selected in the
Python Integrated Tools page of the Settings/Preferences dialog, 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.
So doing, the tags in reStructuredText and epytext markup are highlighted accordingly.
If configured, the documentation
comment stubs can be generated with type
and
rtype
tags.
When you create additional tags, PyCharm provides code completion that suggests the possible tag names.
Prerequisites
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.
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).