Writing docs for Mozbase

Getting started

Install sphinx (sudo easy_install sphinx), and read the tutorial if you aren't familiar with it.
- Sphinx is also installed through setup_development.py.
git clone https://github.com/mozilla/mozbase.git
- or go to https://github.com/mozilla/mozbase and get the url there if you're on the A-Team or otherwise authorized to commit, as the above will give you a read-only copy.
cd mozbase/docs
make html

"Mozbase" is written as "mozbase" normally, as "Mozbase" at the beginning of a sentence, and never as "MozBase" (though there is lingering usage of the latter, particularly in wiki page names).
Modules (e.g. mozfile) should be written as all lower case
Python conventions for writing docstrings:
- ~~http://www.python.org/dev/peps/pep-0216/~~ (superseded by 0287)
- http://www.python.org/dev/peps/pep-0287/
Cpython appears to use sphinx for their documentation: http://hg.python.org/cpython/file/default/Doc

Read: http://packages.python.org/an_example_pypi_project/sphinx.html
Add a toplevel .rst to docs/ (use mozfile as an example)j
Add a link to your module's .rst to index.rst (again, use mozfile as an example)
Modify your .rst to contain the magic strings
- if all classes and functions are public you do not have to list them. Just provide an empty list
Update docstrings so that the generated docs look good
- To get an overview text for your module add a docstring to the __init__.py module
To get updated documentation, run "make clean && make html"
- Sphinx is not smart enough to figure out that it needs to rescan python files included by .rst files. To get around this, run 'make clean && make html' instead of just 'make html'
Profit!