Updating documentation locally using an IDE

Alternatively, you can create a local copy of the project on your computer (forking and cloning the code). You can then edit the source code as desired using your IDE of choice (e.g. PyCharm). You can then follow the best practice guidelines to commit and contribute your code into the project’s main repository through a pull request.

Updating documentation with PyCharm

This section describes how to add a sphinx build configuration to PyCharm:

  1. Open Pycharm.

  2. File → Open → Navigate to your project folder -> Click Ok.

  3. Run → Edit configurations.

  4. Click the + → button on the top left of the window to add a new configuration.

../../../_images/pycharm_edit_configurations.png

Add new run configuration in PhyCharm.

  1. Select python docs → sphinx task

../../../_images/pycharm_add_sphinx_task.png

Add new run configuration in PhyCharm.

  1. Complete the following fields in the configuration task:

  1. Name: Sphinx task

  2. Input: Select the source directory in the documentation folder (typically, the docs/source folder).

  3. Output: Select the build directory in the documentation folder (typically, the docs/build folder, if this does not exist copy paste the path you have specified for the Input above, and replace source with build).

  4. Python interpreter: Select your python interpreter.

  5. Options: -E -a (This options forces rebuild of html).

../../../_images/pycharm_final_sphinx_configuration.png

Example of a Sphinx task in PhyCharm.

  1. Click Ok.

  2. You can now run the configuration by pressing the green play button.

  3. Once you have finished editing the documentation you can commit your changes to your fork of the repository e.g. using Gitkraken, and create a pull request to notify the developers of the main repository that you have changes ready to be pulled into the main repository.

See also

Note that Python provides a markdown plugin that allows for dynamic previewing of markdown files as shown in the figure below:

../../../_images/pycharm_dynamic_markdown_preview.png

PyCharm Markdown preview plugin.

Warning

On occasion, a bug in the extension results very high CPU usage, slowing down the performance of PyCharm. To address this issue, you need to close any open Markdown files and restart PyCharm. Alternatively, you can disable the Markdown plugin.