Adding Documentation to your Application
++++++++++++++++++++++++++++++++++++++++

Pylons comes with support for automatic documentation generation tools like `Pudge <http://pudge.lesscode.org>`_.

Automatic documentation generation allows you to write your main documentation in the docs directory of your project as well as throughout the code itself using docstrings.

When you run a simple command all the documentation is built into sophisticated HTML.

Tutorial
========

First create a project as described in the `Getting Started Guide <getting_started.html>`_.

You will notice a docs directory within your main project directory. This is where you should write your main documentation.

There is already an ``index.txt`` file in ``docs`` so you can already generate documentation. First install Pudge and buildutils like this::

    easy_install pudge buildutils
    
then run the following command from your project's main directory where the ``setup.py`` file is::

    setup.py pudge
    
Pudge will produce output similar to the following to tell you what it is doing and show you any problems::

    running pudge
    generating documentation
    copying: pudge\template\pythonpaste.org\rst.css -> do/docs/html\rst.css
    copying: pudge\template\base\pudge.css -> do/docs/html\pudge.css
    copying: pudge\template\pythonpaste.org\layout.css -> do/docs/html\layout.css
    rendering: pudge\template\pythonpaste.org\site.css.kid -> site.css
    colorizing: do/docs/html\do/__init__.py.html
    colorizing: do/docs/html\do/tests/__init__.py.html
    colorizing: do/docs/html\do/i18n/__init__.py.html
    colorizing: do/docs/html\do/lib/__init__.py.html
    colorizing: do/docs/html\do/controllers/__init__.py.html
    colorizing: do/docs/html\do/model.py.html

Once finished you will notice a ``docs/html`` directory. The ``index.html`` is the main file which was generated from ``docs/index.txt``.

Learning ReStructuredText
=========================

Python programs typically use a rather odd format for documentation called reStructuredText. It is designed so that the text file used to generate the HTML is as readable as possible but as a result can be a bit confusing for beginners. 

Read the reStructuredText tutorial which is part of the `docutils <http://docutils.sf.net>`_ project.

Once you have mastered reStructuredText you can write documentation until your heart's content.

Using Docstrings
================

Docstrings are one of Python's most useful features if used properly. They are described in detail in the Python documentation but basically allow you to document any module, class, method or function, in fact just about anything. Users can then access this documentation interactively.

Try this::

    >>> import pylons
    >>> help(pylons)
        ...

As you can see if you tried it you get detailed information about the pylons module including the information in the docstring.

Docstrings are also extracted by Pudge so you can describe how to use all the controllers, actions and modules that make up your application. Pudge will extract that information and turn it into useful API documentation automatically. 

Try clicking the ``Modules`` link in the HTML documentation you generated earlier or look at the Pylons source code for some examples of how to use docstrings.

Using doctest
=============

The final useful thing about docstrings is that you can use the ``doctest`` module with them. ``doctest`` again is described in the Python documentation but it looks through your docstrings for things that look like Python code written at a Python prompt. Consider this example::

    >>> a = 2
    >>> b = 3
    >>> a + b
    5

If doctest was run on this file it would have found the example above and executed it. If when the expression ``a + b`` is executed the result was not ``5`` doctest would raise an Exception.

This is a very handy way of checking that the examples in your documentation are actually correct.

To run doctest on a module use:

.. code-block:: Python

    if __name__ == "__main__":
        import doctest
        doctest.testmod()

The ``if __name__ == "__main__":`` part ensures that your module won't be tested if it is just imported, only if it is run from the command line 

To run doctest on a file use:

.. code-block:: Python

    import doctest
    doctest.testfile("docs/index.txt")

You might consider incorporating this functionality in your ``tests/test.py`` file to improve the testing of your application.

Summary
=======

So if you write your documentation in reStructuredText, in the ``docs`` directory and in your code's docstrings, liberally scattered with example code, Pylons provides a very useful and powerful system for you.

If you want to find out more information have a look at the Pudge documentation or try tinkering with your project's ``setup.cfg`` file which contains the Pudge settings.
