Parsons has two kinds of documentation. First: the informal guides and notes we keep on this very website. Second: the version controlled docs we keep at https://move-coop.github.io/parsons/.

How can you tell which documentation goes where?

• Documentation tied to specific code, and specific versions of that code, should go in the version-controlled docs at move-coop.github.io. So if you’re adding a new connector or feature to Parsons, you’d want to update the version-controlled docs to explain what the connector/feature does.

• Any other documentation should go on this website.

If you’re not sure, feel free to ask in Slack!

Updating the Website

If you want to update this website, you’ll need to create a PubPub account and then message Shauna to be added to the community. Once you’re added, you can update pages or create new pages. Feel free to ask for more guidance.

Updating the Version-Controlled Documentation

The version-controlled documentation is harder to update (hence why we have this website).

We have a documentation label that may help you find good docs issues to work on. If you are adding a new connector, you will have to create and connect new documentation files. We have detailed instructions for documenting a new connector.

Parsons documentation is built using Sphinx. Sphinx looks for .rst files in the docs/ repository to create the documentation.

When editing documentation, make sure you are editing the source files (with .md or .rst extension) and not the build files (.html extension).

The workflow for documentation changes is a bit simpler than for code changes:

• Fork the Parsons project using the “Fork” button in GitHub

• Clone your fork to your local computer

• Change into the docs folder and install the requirements with pip install -r requirements.txt (you may want to set up a virtual environment first)

• Make your changes and re-build the docs by running make html. (Note: this builds only a single version of the docs, from the current files. To create docs with multiple versions like our publicly hosted docs, run make deploy_docs.)

• Open these files in your web browser to check that they look as you expect.

• Submit a pull request

When you make documentation changes, you only need to track the source files with git. The docs built in the html folder should not be included.

You should not need to worry about the unit tests or the linter if you are making documentation changes only.