Introduction

Pylons comes with support for automatic documentation generation tools like Pudge.

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.

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 we'll install Pudge and buildutils. By default, Pylons sets an option to use Pygments for syntax-highlighting of code in your documentation, so you'll need to install it too (unless you wish to remove the option from setup.cfg):

1
2

$ easy_install pudge buildutils
$ easy_install Pygments

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

1

$ python setup.py pudge

1

$ python setup.py addcommand -p buildutils.pudge_command

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

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 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:

1
2
3

>>> 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:

1
2
3
4

>>> 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:

1
2
3

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:

1
2

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.