Skip to content

Latest commit

 

History

History
78 lines (49 loc) · 2.55 KB

writingdocs.rst

File metadata and controls

78 lines (49 loc) · 2.55 KB
Raw

writingdocs

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.

Installing Sphinx

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

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

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)

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.

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.

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.