Overview

The Documentation section of the Grok web site welcomes your contributions. We welcome any documentation that another Grokker may find helpful.

You will need to register with this web site before you can contribute. A person in the Documentation group will review your content it publish it. The Documentation group is also a very open group, so if you've contributed some content please ask a Grok web site person and they'll add your account to the Grok Documentation group. This will give you full permissions over the Documentation area of the Grok web site.

There is an effort to maintain community documentation that was announced on the mailing list:

Announcement Grok-doc

Content Types

We have two main types of content you can add to the Documentation section right now:

• Create a How-To. A single page of documentation. Bite-sized help that should focus on a single task.
• Create a Tutorial. A multi-page work of documentation. If you are tackling a sizeable asset of documentation, then we recommend that you use the Tutorial content type even if you only write a single page to begin with. The Tutorial is useful if you later want to add pages that are only example code, or want to expand your documentation into a more complete work.

In a few places on the documentation area we currently dislpay "How-To" or "Tutorial" but we may remove these at a later date, since people browsing through documentation will only be interested in navigation by topic or audience and not by content-type.

ReStructured Text

The preferred format for documentation is using ReStructured Text (ReST). You can enable this for your account by going to "Preferences" -> "Personal Preferences" and choose "Basic HTML textarea editor".

If you do not know restructured text, it's a standard Python documentation format that allows you to apply structure to plain text. The ReStructured Text Primer serves as a quick introduction to the format. Also the ReST Extensions page will tell you how you can format your ReST documentation so that source code will have line numbers and syntax highlighting applied to it (yummy!).

While ReStructured Text is our preferred format, if you are only comfortable working in a WYSIWIG editor such as Kupu or already have documentation in HTML format we still welcome your contribution to the site. Our site editors may later on convert HTML into ReStructured Text format where appropriate.

We may take selected content in ReStructured Text format on the web site, and include this as part of the Grok package itself inside the /doc/ directory for the convenience of developers who prefer to access documentation in plain-text.

Documentation Web Site Bugs

There are currently a couple of small bugs in our web site that you may run into. We intend to fix these bugs, but for now ...

When making subsequent edits to ReStructured Text formatted documents, please take care this format is selected before you hit "Save". There is bug with the web site at the moment where it defaults to Plain Text.

You are also prompted for a Format for the Summary field. This field must be plain text. The Summary field is displayed in lots of areas other than the web page, such as RSS feeds, search engine results and other contexts where the only format is plain text.

Editing and Comments

Any documentation which has typos or incorrect information is free to be corrected by anyone in the Documentation group. In addition, members of the Documentation group may incorporate or respond to comments made to documentation to better clarify or improve existing documentation. We will remove comments from the site after we incorporate them into the main body of the text.

Using Roles

Roles are written by enclosing a role-keyword in colons (':') followed by a term that is enclosed in backticks:

:<rolename>:`<term>`

In the rendered document, the rolename should disappear and the term itself be rendered in a special fashion.

Example: a role:

Here we talk about the function :func:`my_function`

This renders as:

Here we talk about the function my_function

In this example, the func role is used to express that my_function is a function name. You can also use whitespaces in the term:

Example: role-term with whitespace:

A more elaborated description: :func:`my_function(param1, param2)`

which renders as:

A more elaborated description: my_function(param1, param2)

There are many more roles than only the func role defined in this package. Please see README.txt for a complete list.

Using Directives

Directives are used to mark a whole block of text as special. Their general syntax is as follows:

.. <directive-name>:: <directive-header>

   <text-block>

It is very important, that the text block is indented. This way, the parser knows that it belongs to the directive.

Example: simple directive:

Normal text.

.. function:: my_func(param1,[ param2=None])

   A function to do something.

   *param1* -- a parameter.

   *param2* -- an optional parameter.

   Use this function with care.

Normal text again.

This will render as:

Normal text.

my_func(param1, [param2=None])

A function to do something.

param1 -- a parameter.

param2 -- an optional parameter.

Use this function with care.

Normal text again.

In this example the function directive is used to indicate, that a complete function description is given. In the text block you can write, whatever you like, as long as it is indented correctly.

Some directives require a text block (or 'body' or 'content') to exist. This includes the version-related directives versionadded, versionchanged and deprecated as well as the seealso directive.

Some directives require a heading. This includes the version-related directives, which take the heading as a version number.

Example: `versionadded` directive:

Normal text.

.. versionadded:: 0.11

   This function was added because of trouble with the core modules.

Normal text again.

This renders to:

Normal text.

Added in version 0.11:

This function was added because of trouble with the core modules.

Normal text again.

You can (and should) nest directives:

Example: nested directives:

Normal text.

.. function:: my_func(param1,[ param2=None])

  A function to do something.

  *param1* -- a parameter.

  *param2* -- an optional parameter.

  Use this function with care.

  .. versionadded:: 0.11

     This function was added because of trouble with the core modules.

Normal text again.

This is rendered as:

Normal text.

my_func(param1, [param2=None])

A function to do something.

param1 -- a parameter.

param2 -- an optional parameter.

Use this function with care.

Added in version 0.11:

This function was added because of trouble with the core modules.

Normal text again.

As you can see, nesting is done simply by more indenting parts. Here, the versionadded directive is written as part of the function-description.

Normal text.

.. code-block:: python

  class Cave(object):
      pass

Normal text (continued).

http://pygments.org/docs/lexers/

.. code-block:: python
   :linenos:

   class Cave(object):
       pass

1
2

class Cave(object):
    pass