PyCharm 2023.1 Help

reStructuredText support

In addition to the support for reStructuredText Docstring Format (PEP 287), PyCharm provides a handy editor for restructured text.

Similarly to the Markdown editor, you can modify reStructuredText files and verify the results in the preview panel.

Editor and preview mode

You can open any existing file with the restructured text or create a new one from scratch.

Create an .rst file

  1. Right-click in the Project tool window and select New | File. In the opened dialog, specify any filename with the .rst extension and click OK.

  2. PyCharm recognizes the file type and marks it with the corresponding icon.

    a file with restructured text
  3. The newly created file opens in the editor. When no text is added, the preview panel is disabled.

Let us add some content to see how PyCharm assists editing restructured text.

Edit the text

  1. In the Settings dialog (Control+Alt+S), review the default color scheme for reStructuredText (Editor | Color Scheme | reStructuredText). If needed, set alternative colors and effects for markup elements.

    setting color scheme for reStructuredText

    Click OK to save the changes and close the window.

  2. Add any section structure markup and preview the results. Note that PyCharm supports markup inspections, so if any error is detected, the problematic line is highlighted in the editor.

    Markup error detected
  3. Add code fragments by using the .. code-block:: directive. PyCharm supports code completion for directive names.

    Code completion for the directive names

    You can enable code syntax highlighting by specifying a particular language in the directive: .. code-block:: python. Also, ensure that your project interpreter has the Pygments package installed.

    Highlighting Python syntax in the code block
  4. If needed, you can quickly mark up links in your text and postpone adding a reference target. PyCharm notifies you and highlights the links that lack references.

    All you need is to add the proper target reference to the reStructuredText file, for example, .. _pytest: https://docs.pytest.org/.

    Valid links
Last modified: 10 March 2022