5.12. Writing documentation¶
To contribute with your documentation follow these steps to be able to modify the git repo, build a local copy and deploy on ReadTheDocs.org.
5.12.1. Installing Sphinx¶
pip install sphinx
5.12.2. Making the HTML¶
Now you can build the docs with this simple command:
cd docs make html
This should update the revelant HTML files in socorro/docs/_build and you can preview it locally like this (on OS X for example):
To modify the index itself, edit index.rst and (for instance you may want to add or remove a document filename, without the rst extension, from the ”.. toctree::” section)
5.12.3. Making it appear on ReadTheDocs¶
ReadTheDocs.org is wired to build the documentation nightly from this git repository but if you want to make documentation changes appear immediately you can use their webhooks to re-create the build and update the documentation right away.
5.12.4. Or, just send the pull request¶
If you have a relevant update to the documentation but don’t have time to set up your Sphinx and git environment you can just edit these files in raw mode and send in a pull request.
5.12.5. Or, just edit the documentation online¶
The simplest way to edit the documentation is to just edit it inside the Github editor. To get started, go to https://github.com/mozilla/socorro and browse in the docs directory to find the file you want to edit.
Then click the “Edit this file” button in the upper right-hand corner and type away.
When you’re done, write a comment underneath and click “Commit Changes”.
If you are unsure about how to edit reStructuredText and don’t want to trial-and-error your way through the editing, then one thing you can do is to copy the text into an online reStructuredText editor and see if you get the syntax right. Obviously you’ll receive warnings and errors about broken internal references but at least you’ll know if syntax is correct.