a quick guide to updating our documentation
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!
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.
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
.rst extension) and not the build files (
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
Open these files in your web browser to check that they look as you expect.
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.