5.6. Updating documentation

Once you have created the documentation, there are a number of ways to allow others to update it.

Note

As part of best practice guidelines, it is recommended to use a version control system for tracking commits to your code and host your code on a online version control service such as github. The following assumes you are following these best practice guidelines.

Important

See the best practices guide for more information on the how to contribute software projects.

Updating documentation online

You can directly edit existing documentation online, for example on github. This approach allows you to contribute changes using only a web browser.

Navigate to the repository of interest.
If the repository does not belong to you, fork the repository, (part of the best practice guidelines). You can do this by clicking on the fork icon on the top right of the repository. This will create a copy of the repository on your github account.
In the project, select the file that you wish to edit (e.g. a file ending with .md (Markdown) or .rst (reST)). The rendered preview of the file will appear.
Click on the pencil button as shown in the screenshot below to edit the file.

Editing documentation on github.

This will open the editor mode showing the file in markup format.

Editing mode on github.

Make edits.
Preview edits by clicking on the Preview tab.

Previewing changes on github.

Once you are finished, scroll to the bottom of the page to the Section named Commit changes.

Add a title to your commit that summarises the change that you made.

Add an optional extended description.

Committing changes on github.

Decide whether you want to commit directly to the master branch or make the commit to a new branch and start a pull request (best practice guidelines recommend the latter option.
Create a pull request from your fork to the main repository. This will allow the owner of the main repository to review your changes and determine whether it can be contributed back into the main repository.

Important

See the best practices guide for more information on the how to contribute software projects.

For additional information see the following outline on contributing to documentation via github.

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:

Open Pycharm.
File → Open → Navigate to your project folder -> Click Ok.
Run → Edit configurations.
Click the + → button on the top left of the window to add a new configuration.

Add new run configuration in PhyCharm.

Select python docs → sphinx task

Add new run configuration in PhyCharm.

Complete the following fields in the configuration task:

Name: Sphinx task

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

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

Python interpreter: Select your python interpreter.

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

Example of a Sphinx task in PhyCharm.

Click Ok.
You can now run the configuration by pressing the green play button.
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.