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

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.

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 is selected in the 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).

Sphinx cross-references

In docstrings and line comments, PyCharm recognizes Sphinx cross-references to Python objects: Python-domain roles, such as :py:class: and :py:func:. In docstrings, PyCharm also recognizes directives that describe Python objects, such as .. py:class::.

            def connect(timeout=None):
                """Open a connection.

                :param timeout: Timeout in seconds. The default is :py:func:`socket.getdefaulttimeout`.
                :return: A :py:class:`socket.socket` object.
                """
        

Each component of a dotted target is a separate reference. For example, in socket.getdefaulttimeout, both socket and getdefaulttimeout are references. You can work with them as with any other Python reference:

Navigate to the declaration of an object.
Find usages of an object, including its cross-references.
Rename an object. PyCharm updates all cross-references that include it, no matter which component of the target it is.
Move an object. PyCharm updates the targets of the cross-references to the import path from which the object is available. For example, if a package re-exports an object from a private module, the target uses the package path.

Unresolved references

PyCharm highlights an unresolved target only if the first component of its path resolves. Sphinx can resolve targets from objects that are not available in your project, so other targets are not highlighted. PyCharm never highlights the following targets:

Targets that start with a dot, for example, :py:meth:`.close`. Sphinx resolves them by searching for a matching object.
Names in directive signatures. Sphinx qualifies these names by the current module and by the enclosing directive.

Spelling and grammar

The spellchecker and the grammar checker skip the targets of all reST roles, including roles that do not refer to Python objects, such as :ref:.

Injected code

PyCharm does not recognize cross-references in code with an injected language, for example, in the body of the .. code-block:: python directive. Sphinx does not process markup there either.

02 November 2026