Since TurboGears 1 has been superseded by TurboGears 2, we consider the documentation efforts in this Wiki as completed. The Wiki will be closed and its content will be transferred into a more static documentation system like Sphinx. This page is only kept as historical reference.
There are three ways to help make and maintain TurboGears documentation:
All docs about the TurboGears framework must have a version number at the beginning of the page name (i.e the last part of the URL), in sub wiki syntax. If you write a page about Apache deployment for TurboGears 1.0, that page should be called "1.0/ApacheDeployment".
New articles should be linked from the :doc:`RoughDocs <1.0/RoughDocs>` page for the applicable version (e.g. 1.0/RoughDocs) until they have been reviewed and approved by the editors and given "official" status. This also ensures that new documents don't get lost and others can benefit from and/or contribute to them immediately.
Multi-page documents should use the sub wiki format to reflect the pages, e.g. "1.0/20MinuteWiki/Page1".
In an effort to keep the documentation consistent online and useful offline, please follow these conventions:
All documentation should be in ReStructuredText (ReST) format, not the standard wiki markup .
There are two templates that should be used to get you going with your document. Both templates set the format to ReST Formatting and they also include the proper code to include the page comment form.
Please note that if you choose not to use one of these templates you will have to explicitly tell MoinMoin that you are using ReST syntax. This is done by adding the following code to the top of the page, before any text:
Proper ReST formatting syntax is discussed below.
All documentation pages should display their editorial status right below the main heading (like this page does). Use the field lists syntax for the status tag:
This is the Page Title ====================== :Status: Draft
Status tag values should be one or several of "Official", "Contributed", "Work in Progress", "Draft", "Approved", "Obsolete", "Not verified" etc.
All pages longer than a screen page should have a table of contents. This will be generated automatically by the wiki software from the section headings if you include this markup directly after the status tag:
.. contents:: :depth: 2
The depth option tells the ReST parser how many heading-levels should be included in the table of contents.
Treat the ReST source as you would treat Python source code by making it nicely formatted and beautiful. When it helps, you can edit the page source in your local editor and paste it back into the wiki editor interface when you are ready.
Wrap ReST source lines at 80 characters.
Insert two empty lines before and one after each heading.
Keep the indentation of literal blocks consistent.
The page title should be underlined with equal signs (=).
Section headings should be underlined with - (dash), ~ (tilde), and ` (backtick), according to their level in the section hierarchy, in the order given here. Keep the underline the same length as the section title.
Literals are any chunk of code, including variable names and parameters and anything you type directly into a terminal. Literals are surrounded by double backticks. (If you run across one of the few instances of the older convention of surrounding literals with quotes, please drop the quotes and replace with double backticks.)
Block literal sections are for longer examples and command lines.
If you have a block literal section, and the preceding line ends with a colon, just double that colon. For example, instead of inline style tg-admin info, you would write:
Please run:: tg-admin info
Please notice the empty line after the double colon and the indentation of the literal block (the command).
With this form there will be one colon at the end of the line preceding the literal block in the output. If you don't want this, you can put the double colon on a single line and it will not show in the output:
:: foo = Bar()
Links should be marked up in the standard ReStructured Text callout style:
This is an `example link`_. .. _example link: 1.0/ExampleLink
Try to use list syntax for lists instead of formatting the lists yourself with bold or italics. This mostly comes up when dealing with lists of arguments etc. The :doc:`Configuration <1.0/Configuration>` page is a good example:
``arg1`` argument 1 explanation text ``arg2`` argument 2 explanation text
First-level lists have no indentation in the ReST source.
For ordered lists, don't number the items yourself. Use this syntax instead:
#. Item one #. Item two #. ...
You can also break lines in lists, footnotes and notes, if you indent the second and following lines the same level.
For list items, the indentation level must match that of the first letter on the first line, e.g.:
* This is a multi-line list item. #. List items can have several paragraphs. Like this.
Remember, pages marked with "Official[, Approved]" are considered to be accurate, reviewed and have proper style. Copy editing is an essential part of maintaining high quality documents.
While working on a new document, set the status to "Work in progress".
Once completed to your satisfaction,
If you work on a document that is marked Official,
|||Comment sections have been increasingly locked up due to wiki spamming. Sorry for this inconvenience.|
|||Rough docs sections are closed now, the remaining content will be merged into the official sections.|
|||This is very important for ensuring the long term value of the docs we write. We expect to move to another documentation system at some point in the future (probably Sphinx), or we might want to convert the docs to printable form. The use of ReStructuredText will allow us to do that without complex document conversions.|