Contributing to the documentation

This documentation uses Python-sphinx [1]. It uses reStructuredText [2] syntax.

Conventions

Language

The documentation is written in english.

Line length

Limit all lines to a maximum of 79 characters.

Headings

Use the following symbols to create headings: #  *  =  -

As an example:

##################
H1: document title
##################

*********
Sample H2
*********

Sample H3
=========

Sample H4
---------

And sample text.

If you need more than H4, then consider creating a new document.

Code blocks

Combine a “highlight” directive and a ”::” to specify the programming language. As an example:

.. highlight:: python

::

  import this

Warning

“code-block” and “sourcecode” directives are not natively supported by rst2html, which is used by Github’s repository browser, i.e. those lines won’t appear on Github. Whereas ”::” lines will.

Install Sphinx

Python-sphinx [1] installation is covered in Install a development environment for lettuce.

In other cases, please refer to Python-sphinx [1] documentation.

Export documentation to HTML

  • Install Python-sphinx [1].

  • Make sure sphinx-build is in your shell’s $PATH. If you are using virtualenv as told in Install a development environment for lettuce, then activate your virtual environment.

  • Go to lettuce folder and use the provided Makefile:

    make documentation
    
  • HTML documentation is exported to docs/_build/html/.

Use doctests!

This documentation uses the Sphinx’s doctest extension [3].

Write doctests

Here is a RST code sample to write doctests. You can find some doctests in the “terrain”.

.. highlight:: python

.. doctest::

   >>> print "Hello world!"
   Hello world!

See Sphinx’s doctest extension [3] and Python’s doctest [4] documentations for details.

Run doctests

Go to lettuce folder and use the provided Makefile:

make doctests