Tree [r7423] / tags / 1.1b3 / doc /

File Date Author Commit
README.txt 2008-04-25 carndt [r4508] Sync API doc generation script with 1.0 branch 2008-04-26 carndt [r4510] Add reference to README.txt to usage msg for AP...
doc.ini 2008-04-25 carndt [r4508] Sync API doc generation script with 1.0 branch

Read Me

API Documentation Generation Guide

You need to install epydoc_ 3 first to generate the TurboGears API
documentation from the source code.

You can install it via easy_install_::

    $ easy_install "epydoc>=3.0"

Checking for missing doc strings

To check which docs need to be written, use the following command in the
top directory of the TurboGears 1.1 branch::

    $ epydoc --check turbogears

The command will check that every module, class, method, and function has a
description; that every parameter has a description and a type; and that every
variable has a type. It will list those that don't meet these requirements.

Generating HTML docs

Use this command in the top directory::

    $ ./doc/

to generate the API documentation in the ``doc/api`` folder.

You can change the settings in the file ``doc.ini`` in the ``doc`` folder to
customize the output.

Writing docs

.. note:: The TurboGears project uses reStructuredText_ format for doc strings.

It's a bit different from epydoc's default format. Check the documentation
about using reStructuredText with epydoc on the epydoc web site:


Debugging docs

If you get a formatting error and want to locate the position in the source
quickly, use the verbose mode of epydoc by supplying the ``-v`` option and
epydoc will print comprehensive debugging output.

The verbose mode is enabled in ``doc/doc.ini`` by default.

.. _epydoc:
.. _reStructuredText:
.. _easy_install: