Introduction for documenting

Some hints on writing documentation with Sphinx for web2py

Writing documentation

official documentation

• Sphinx

Docstrings

• official python standard

  • Docstring Conventions
  • Documenting Python

• numpy standard

  • documentation standard

  • Example file

  • Docstring Template

    If you use Eclipse / Pydev you can define this piece as template.

Helpers

Editors

• Emacs: see docutils page
• Gedit (Linux)
• Ulipad (Win)

Others

• creating tables in ReST can be painful. Here is a module that can help:

  easy_install prettytable
  import prettytable as pt
  mytable =pt.PrettyTable(["id", "category", "recipie"])
  print mytable # copy & paste this into your ReST document!
  mytable_string = mytable.get_string() # or insert this string when
  generating automatic documents

Building documentation

Follow these steps:

1. easy_install -U sphinx

2. built with custom make files for web2py => Note: we could create a cross-platform python script for this!

   1. unix-like: sh doc/make-doc_html.sh
   2. windows: doc\make-doc_html.bat

   Due to the special manner of the web2py import mechanism it requires that the doc is built from the web2py root directory.

3. the result will written to: web2py/applications/examples/static/sphinx (the target directory will be automatically created)

4. inspect any error

   1. on the CLI: see the errors and warnings floating on stderr/stdout
   2. using the above mentioned make files a log file will be written to web2py/doc/sphinx-build.log

Contributing

Warning

Please ask on the Mailinglist before commiting or pushing to the repositories.

So far, it has not been agreed on a proper setup to mutually edit the documentation and especially how to correct the docstrings without getting to many DVCS conflicts.

1. branch the web2py Sphinx code:

   bzr branch lp:~web2py/web2py/web2py-sphinx
   cd web2py-sphinx

2. pull the latest code from web2py Sphinx branch:

   bzr pull

3. pull latest web2py development version:

   bzr pull http://bazaar.launchpad.net/~mdipierro/web2py/devel/

4. change and edit the documents or docstrings with your edior

5. push the changes to the web2py Sphinx branch:

   bzr push lp:~web2py/web2py/web2py-sphinx

   This requires that you are a member of the web2py team at Launchpad and registered at Launchpad with your SSA keys. You can find more info on the Launchpad help page