Using the Twisted Documentation

Twisted includes a few different types of documentation: extensive API documentation, HOWTOs, a tutorial, and sample code. It's a good idea to familiarize yourself with this documentation now, so that you'll be able to refer to it during the development process.

1.4.1. How Do I Do That?

Documentation for Twisted is available online on the Twisted web site. A complete API reference can be found at http://twistedmatrix.com/documents/current/api. You'll probably refer to this documentation many times to see which classes a module contains or to see the list of arguments for a specific function. The pages in the API documentation are automatically generated from the source code using lore, a custom documentation tool developed as part of Twisted.

Twisted is developed as a set of subprojects, and each project has additional documentation in its section of the Twisted site. For example, documentation on the core modules is at http://twistedmatrix.com/projects/core/documentation, and documentation on web modules is at http://twistedmatrix.com/projects/web/documentation. There are links to the full list of projects and documentation on the home page.

Within each project's documentation, you'll find the following types of information:

HOWTOs

These documents describe specific features of Twisted and how to use them. The HOWTOs don't cover every part of Twisted, but they can provide a helpful starting point for certain tasks. Included in the HOWTOs is a tutorial called "Twisted From Scratch," which shows how an application can be developed in Twisted, extended to take advantage of some advanced features, and then fully integrated with the Twisted utilities.

Examples

These are examples of short and specific Twisted programs. Like the HOWTOs, these aren't comprehensive but can be an excellent resource when you need a working example of a certain feature.

Manual pages

These are HTML versions of the manpages describing how to use the Twisted utilities.

1.4.2. What About...

...viewing the API documentation without using a browser? If you'd prefer, you can view the API documentation using the standard pydoc utility. pydoc doesn't understand all of the conventions used in the Twisted internal documentation, but it's still quite usable. Figure 1-1 shows output from the command pydoc twisted.web.http.

Also, when you really want to understand how a part of Twisted works, you can always read the source code. With the exception of a few modules that are written in C for better performance, you don't even need the source distributionjust go to your Python lib directory, look under site-packages/twisted, and open the appropriate .py file in your favorite editor.