Introduction

These are a few guidelines for Ganeti code and documentation.

Docstrings

Note: PEP 257 is the canonical document, unless epydoc overrules it (e.g. in how to document the type of an argument).

For docstrings, the recommended format is epytext, to be processed via epydoc. There is an apidoc target that builds the documentation and puts it into the doc/api subdir. Note that we currently use epydoc version 3.0.

Note that one-line docstrings are only accepted in the unittests.

Rules for writing the docstrings (mostly standard Python rules):

• the first line should be a sentence, with punctuation at the end
• the second line should be blank
• afterwards the rest of the docstring
• special epytext tags should come at the end
• multi-line docstrings must finish with an empty line

Example (see also http://epydoc.sourceforge.net/manual-epytext.html):

  def fn(foo, bar):
    """Compute the sum of foo and bar.

    This functions builds the sum of foo and bar. It's a simple function.

    @type foo:  int
    @param foo: First parameter.
    @type bar:  float
    @param bar: The second parameter. This line is longer
                to show wrapping.
    @rtype:     float
    @return:    the sum of the two numbers

    """
    return foo + bar

Rules for classes and modules

As PEP 257 says, the docstrings of classes should document their attributes, and the docstrings of modules should shortly document the exported functions/variables/etc. See for example the pydoc output for the os or ConfigParser standard modules.