git commit: docs: Add costrings conventions section (moved from the site).

[to...@apache.org]

Updated Branches:
  refs/heads/trunk bd1d3b1a1 -> cb72aea4b


docs: Add costrings conventions section (moved from the site).


Project: http://git-wip-us.apache.org/repos/asf/libcloud/repo
Commit: http://git-wip-us.apache.org/repos/asf/libcloud/commit/cb72aea4
Tree: http://git-wip-us.apache.org/repos/asf/libcloud/tree/cb72aea4
Diff: http://git-wip-us.apache.org/repos/asf/libcloud/diff/cb72aea4

Branch: refs/heads/trunk
Commit: cb72aea4ba980c88df92f8480365dea78a69d7fb
Parents: bd1d3b1
Author: Tomaz Muraus <to...@apache.org>
Authored: Sun Dec 15 20:19:43 2013 +0100
Committer: Tomaz Muraus <to...@apache.org>
Committed: Sun Dec 15 20:21:08 2013 +0100

----------------------------------------------------------------------
 docs/development.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/libcloud/blob/cb72aea4/docs/development.rst
----------------------------------------------------------------------
diff --git a/docs/development.rst b/docs/development.rst
index 755fb4f..29d12c0 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -44,6 +44,37 @@ After you have installed this hook it will automatically check modified Python
 files for violations before a commit. If a violation is found, commit will be
 aborted.
 
+Docstring conventions
+---------------------
+
+For documenting the API we we use Sphinx and reStructuredText syntax. Docstring
+conventions to which you should adhere to are described bellow.
+
+* Docstrings should always be used to describe the purpose of methods,
+  functions, classes, and modules.
+* Method docstring should describe all the normal and keyword arguments. You
+  should describe all the available arguments even if you use ``*args`` and
+  ``**kwargs``.
+* All parameters must be documented using ``:param p:`` or ``:keyword p:``
+  and ``:type p:`` annotation.
+* ``:param p: ...`` -  A description of the parameter ``p`` for a function
+  or method.
+* ``:keyword p: ...`` - A description of the keyword parameter ``p``.
+* ``:type p: ...`` The expected type of the parameter ``p``.
+* Return values must be documented using ``:return:`` and ``:rtype``
+  annotation.
+* ``:return: ...`` A description of return value for a function or method.
+* ``:rtype: ...`` The type of the return value for a function or method.
+* Required keyword arguments must contain ``(required)`` notation in
+  description. For example: ``:keyword image:  OS Image to boot on node. (required)``
+*  Multiple types are separated with ``or``
+   For example: ``:type auth: :class:`.NodeAuthSSHKey` or :class:`.NodeAuthPassword```
+* For a description of the container types use the following notation:
+  ``<container_type> of <objects_type>``. For example:
+  ``:rtype: `list` of :class:`Node```
+
+You can find some examples in the following file: https://github.com/apache/libcloud/blob/trunk/libcloud/compute/base.py
+
 General guidelines
 ------------------