Writing docs for Mozbase
- 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:
- 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'