Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

[r7423]: docs / wiki / DocHelp.rst Maximize Restore History

Download this file

DocHelp.rst    393 lines (247 with data), 11.9 kB

Contributing Documentation to TurboGears

status:Official

The Revolution is Over

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.

contribute_docs

Three Ways to Help

There are three ways to help make and maintain TurboGears documentation:

  1. Comment! Pages should all have a comments box at the bottom [1]. Add your comments if you see a problem.
  2. :ref:`Add to the RoughDocs` section for the version of TurboGears you're using [2]. Anyone can add and edit documentation there, following the directions below. Please do!
  3. Become an editor! Knowledgeable TurboGears users with the interest and aptitude can become editors. Editors are able to edit the "official" docs. To get involved, visit the :doc:`documentation team page </DocTeam>`.

How to Add or Change Documentation

Putting Docs in the Right Places

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".

Documentation Format & Style Guidelines

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 [3].

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.

:doc:`OfficialTemplate`
For official docs, this template ensures that only editors can edit.
:doc:`TurboGearsTemplate`
For any contributed or unofficial docs.

Designating ReST Syntax

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:

#format rst

Proper ReST formatting syntax is discussed below.

Page Status

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.

Table of Contents

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.

Language & Style

  1. Please pay attention to proper spelling, grammar, and style! For example,
    • All full sentences should end with a full stop.
    • Proper names should be capitalized.
    • Common word contractions should be written out (i.e. "you should" instead of "you'd", etc.).
  2. Avoid too many abbreviations and jargon speak.
  3. Avoid slang and idioms (e.g. "This should be a piece of cake."). Not every reader of the docs is a native English speaker so it will not always mean what you meant it to mean!
  4. All major words in the page title and headings should be capitalized (e.g. "This is a Good Heading", but "This is not a good heading"). The exceptions are articles, conjunctions, and short prepositions, etc.
  5. Use literal syntax (see below) for names of Python objects, functions, modules etc., shell commands, software packages, and so on.
  6. A full command line should go in a block literal (see below) so that it is easier to notice.
  7. The generic placeholder for the name for an example project (e.g. Wiki 20) is <projectname> and the Python package name (e.g. wiki_20) is <packagename>.

ReST Formatting

Some markup guidelines and essentials of ReST syntax are listed below. For summary reference, visit this Quick Reference page or this more extensive list.

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.

  1. Wrap ReST source lines at 80 characters.

  2. Insert two empty lines before and one after each heading.

  3. Keep the indentation of literal blocks consistent.

  4. The page title should be underlined with equal signs (=).

  5. 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.

  6. 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.)

  7. 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()
    
  8. Links should be marked up in the standard ReStructured Text callout style:

    This is an `example link`_.
    
    .. _example link: 1.0/ExampleLink
    
    • If the URL is very long, you can put a line break after the colon and indent the URL on the next line.
    • Put the all URLs from one section at the end of the section.
    • One-word links don't need backticks: :doc:`/mylink`.
    • The link target should not be enclosed in backticks and is not case- sensitive.
  9. 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
    
  10. First-level lists have no indentation in the ReST source.

  11. For ordered lists, don't number the items yourself. Use this syntax instead:

    #. Item one
    #. Item two
    #. ...
    
  12. 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.

Document Submission Procedure

Newly Created Documents

While working on a new document, set the status to "Work in progress".

Once completed to your satisfaction,

  1. Change status to "Draft".
  2. Open a new Trac ticket requesting a review. (See Opening New Document Tickets below.)

Improvements upon Existing Documents

Editable Documents

  • If you think you know what you are doing:
    1. Edit document directly.
    2. Do not open a ticket.
  • If you have doubts:
    1. Edit what you can.
    2. Open one ticket for review and all the rest of the issues with that page.

Official Documents

If you work on a document that is marked Official,

  • If you have write access:
    1. Please take extra care.
    2. Set the status to "Official, Draft" until at least one other person has had a chance to look at your changes.
    3. Open a new ticket requesting review of your changes.
  • If you do not have write access:
    1. Download the raw text of the original document.
    2. Make changes at your local computer.
    3. Create a diff file of your changes with diff -u old new.
    4. Open a new ticket.
    5. Attach diff file to ticket.

Opening New Document Tickets

  1. Open a new Trac ticket.
  2. Put the document's title in the ticket summary
  3. Set Component=Docs
  4. Set Version=X.0 (one decimal place only)
  5. For review requests, set the keywords to "doc review", for patches to official pages, set the keywords to "doc update".
  6. If you could not edit the document yourself, attach a diff file of your proposed changes and put [PATCH] in the summary of the ticket

Resources


[1]Comment sections have been increasingly locked up due to wiki spamming. Sorry for this inconvenience.
[2]Rough docs sections are closed now, the remaining content will be merged into the official sections.
[3]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.