Text editors: Write the source#

You can use any text editor you like to write reStructuredText (RST) files or docstrings in Python files. We do recommend using an editor that provides RST syntax highlighting, however. This will be especially helpful if you are unfamiliar with RST.

There are also several websites that will provide a preview of how the RST will render in HTML, but those work only for the RST syntax itself; markup specific to Sphinx, such as directives or variables, will not render because they must be compiled during the Sphinx build process. Similarly, they have little benefit when writing docstrings because the format is a special flavor of RST and the API reference topics built from docstrings require information gleaned from the Python code.

If you still want to try one of these web-based RST previewers given those limitations, we recommend the following:

PyCharm#

PyCharm provides some nice tools for writing RST files and docstrings in Python files.

To automatically create stubbed out docstrings in Python files:

  1. Open File > Settings > Tools > Python Integrated Tools.

    _images/pycharm-1.png

  2. Under Docstrings > Docstring format, select Google.

    _images/pycharm-2.png

    When you type three quote marks after an object definition, this setting will create a stubbed out Google style docstring that lists all arguments or other information pulled from the definition.

To make documentation links clickable in the IDE:

  1. Open File > Settings > Tools > External Documentation.

  2. For your project, enter the URL for the documentation hosted on Read the Docs. This will be in the format https://docs.idmod.org/projects/<project-name>/

    _images/pycharm-3.png

    When you select an object in the Python file and press Ctrl+Q, this setting will display the documentation for the object, rendering any link text as clickable links to the project’s HTML documentation. Links to other projects will not be clickable because they require Sphinx compilation.

Sublime Text#

The documentation team likes Sublime Text, which displays RST syntax highlighting by default and has several color schemes to choose from. It has some other helpful features that are off by default or that require you to install separate packages.

We recommend the following settings for RST files:

  1. Open Preferences > Settings. Add the following:

    "spell_check": true,
"translate_tabs_to_spaces": true,
"trim_trailing_white_space_on_save": true,
"rulers": [80, 100]

  2. Select View > Indentation > Indent Using Spaces.

Additionally, pressing Alt-Q will create line breaks at 80 characters. The recommendation is to limit lines to 80-100 characters, hence the addition of a ruler to remind you to shorten long lines. This will also aid in Sphinx build troubleshooting because the line number indicated in the error message will contain less content.

To install additional packages:

  1. Open Preferences > Package Control:

  2. Select Install Package and search for packages you want to install. Some packages we like:

    • GitGutter: Displays the Git diff and latest commit.

    • AutoDocstring: Automatically creates stubbed out docstrings in your desired format (we use Google style Python docstrings).

Notepad++#

You can add a plug-in to provide syntax highlighting in Notepad++ (steenhulthin/reStructuredText_NPP).

Visual Studio#

Visual Studio requires installation of the reStructuredText extension from LeXtudio. This provides code snippets, RST syntax highlighting, and live preview.