This document is the latest information about how documentation is produced for TurboGears.org. There is a spot for "unofficial" docs in the Documentation Playground on the TurboGears Trac, but this is not really the preferred way to create documentation. Ultimately, the docs in the playground need to be cleaned up and converted to proper docs and deleted from the wiki as this happens. If docs can start out in the right format, then we're better off.
Eventually, the docs will be imported into a Docudo instance. This will make it possible for people to easily edit docs through svn checkouts or through the web. Once Docudo is in place, the Documentation Playground will go away.
For now, however, this is the process.
The turbogears.docgen module is responsible for generating the static portions of the TurboGears site.
TurboGears docs are authored in XHTML, because it's a language that everyone understands and it translates quite well to the web. By using XHTML, we're able to conveniently do things like syntax highlighting using JavaScript.
The docs are Kid templates which have site-wide styling applied via py:match rules. Generally speaking, there's not much else that's special about it. The main trick is that if you're writing about Kid, you'll need to use two $ symbols whenever you want to show off $${} variable interpolation.
The basic boilerplate for a new document file is in newdocs/newfile.html. That extends the main content template for the site.
Other kinds of files (images, css files, javascript files) will all get copied as-is over to the final site. When building the site, docgen makes a mirror of the original directory. So, if you delete a file, that file will get deleted from the site with no additional work required.
docgen has a crude ability to make versions of documents that are "printable". The printable documents have a different template applied which removes all of the navigation elements from the page. This same effect could likely be achieved via CSS. However, something else that is done by docgen's printable feature is to combine multiple documentation files into one. The "20 Minute Wiki" tutorial was what these feature was created for originally. The tutorial was broken into 6 pages, but the desired printable form was just a single page. Since the TG docs are XHTML, using standard XML techniques it was possible to combine the files into a single file and apply the printable template to get nicer output.
The printable document generator does not get applied to every doc. This is where CSS would be a nicer solution. Also, the printable generator doesn't check to see if the original files had changed at all: it just always generates. Finally, it's not really written in a convenient, generic way to easily apply it to additional files.
If you'd like to see how the final, rendered docs would look, you can easily do so by running this command:
python setup.py localsite
This will create a copy of the site in dist/docs. Note: the large video files and the download eggs are not included in that version of the site. Those are copied in separately when building the real site.