Auto-tools/Projects/MozBase/WritingDocs

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

Conventions

• "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

Procedure

• 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!

Note: if you are documenting a new module you will need to add it to sys.path here: https://github.com/mozilla/mozbase/blob/master/docs/conf.py#L20