5.2 Renderable Objects

The Renderable class is the real workhorse of the rendering process. It traverses the document object, looks up the appropriate rendering methods in the renderer, and generates the output files. It also invokes the image generating process when needed for parts of a document that cannot be rendered in the given output format.

Most of the work of the Renderable class is done in the __unicode__ method. This is rather convenient since each of the rendering methods in the renderer are required to return a unicode object. When the unicode function is called with a renderable object as its argument, the document traversal begins for that node. This traversal includes iterating through each of the node’s child nodes, and looking up and calling the appropriate rendering method in the renderer. If the child node is configured to generate a new output file, the file is created and the rendered output is written to it; otherwise, the rendered output is appended to the rendered output of previous nodes. Once all of the child nodes have been rendered, the unicode object containing that output is returned. This recursive process continues until the entire document has been rendered.

There are a few useful things to know about renderable objects such as how they determine which rendering method to use, when to generate new files, what the filenames will be, and how to generate images. These things are discussed below.