.. index:: writingdocs
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.
Sphinx is an external tool that compiles these reStructuredText into
HTML. Since it's a python tool you can install it with
easy_install
or pip
like this:
pip install sphinx
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):
open _build/html/index.html
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)
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.
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.
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.