PyCharm
 
2021.2
Shortcuts: Windows
Get PyCharm
You are viewing the documentation for an earlier version of PyCharm.
  1. Work with source code
  2. reStructuredText support

reStructuredText support

Last modified: 08 March 2021

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. You can switch between the available editing modes by using the corresponding icons. Editing and preview modes reflect the currently selected PyCharm user interface appearance.

Editor only 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 file name 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 window. When no text is added, the Preview is disabled.

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

Edit the text

  1. In the Settings/Preferences dialog Ctrl+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 switch to the split view mode to preview the results. Note that PyCharm supports markup inspections, so if any error is detected, the problematic line is highlighted in the Editor panel and the corresponding error message is shown in the Preview panel.

    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 markup links in your text and postpone adding a reference target. PyCharm notifies you and highlights the links that lack references.

    Links that lack reference targets

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

    Valid links

If you experience any problems previewing your content, try to alter the type of the Preview panel. In the Settings/Preferences dialog Ctrl+Alt+S, navigate to Languages & Frameworks | ReStructrued Text, then select JavaFX or Swing from the Preview panel list, click OK, and resume editing the .rst file.

See also

External Links