libcloud-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From to...@apache.org
Subject [1/6] git commit: docs: Update development section.
Date Sun, 05 Jan 2014 22:29:58 GMT
Updated Branches:
  refs/heads/trunk 411877f45 -> 11c9f00ef


docs: Update development section.


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

Branch: refs/heads/trunk
Commit: 983c3f8a83c71cd9a3a3de43ebca4e01a645afda
Parents: 411877f
Author: Tomaz Muraus <tomaz@apache.org>
Authored: Sun Jan 5 22:37:44 2014 +0100
Committer: Tomaz Muraus <tomaz@apache.org>
Committed: Sun Jan 5 22:48:06 2014 +0100

----------------------------------------------------------------------
 docs/development.rst | 48 +++++++++++++++++++++++++++++------------------
 1 file changed, 30 insertions(+), 18 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/libcloud/blob/983c3f8a/docs/development.rst
----------------------------------------------------------------------
diff --git a/docs/development.rst b/docs/development.rst
index 30b7568..e494cea 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -1,18 +1,32 @@
 Development
 ===========
 
+This page describes Libcloud development process and contains general
+guidelines and information on how to contribute to the project.
+
 Contributing
 ------------
 
 We welcome contributions of any kind (ideas, code, tests, documentation,
 examples, ...).
 
-This page explains how you can contribute to the Libcloud project. If you get
-stuck at any point during this process, stop by on our IRC channel (#libcloud
-on freenode) and we will do our best to assist you.
+If you need help or get stuck at any point during this process, stop by on our
+IRC channel (:ref:`#libcloud on freenode <irc>`) and we will do our best to
+assist you.
+
+General contribution guidelines
+-------------------------------
 
-Style guide
------------
+* Any non-trivial change must contain tests. For more information, refer to the
+  :doc:`Testing page </testing>`.
+* All the functions and methods must contain Sphinx docstrings which are used
+  to generate the API documentation. For more information, refer to the
+  :ref:`Docstring conventions <docstring-conventions>` section bellow.
+* If you are adding a new feature, make sure to add a corresponding
+  documentation.
+
+Code style guide
+----------------
 
 * We follow `PEP8 Python Style Guide`_
 * Use 4 spaces for a tab
@@ -23,7 +37,7 @@ Style guide
   ``tox -e lint``.
   Second command fill run flake8 on all the files in the repository.
 
-And most importantly, follow the existing style in the files you are editing and
+And most importantly, follow the existing style in the file you are editing and
 **be consistent**.
 
 Git pre-commit hook
@@ -44,11 +58,13 @@ 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.
 
+.. _code-conventions:
+
 Code conventions
 ----------------
 
-This section contains some conventions you should follow when writing a
-Libcloud code.
+This section describes some general code conventions you should follow when
+writing a Libcloud code.
 
 1. Import ordering
 ~~~~~~~~~~~~~~~~~~
@@ -57,7 +73,7 @@ Organize the imports in the following order:
 
 1. Standard library imports
 2. Third-party library imports
-3. Local libray (Libcloud) imports
+3. Local library (Libcloud) imports
 
 Each section should be separated with a blank line. For example:
 
@@ -176,6 +192,8 @@ For example:
             if domain is not None:
                 params['Domain'] = domain
 
+.. _docstring-conventions:
+
 Docstring conventions
 ---------------------
 
@@ -205,16 +223,10 @@ conventions to which you should adhere to are described bellow.
   ``<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
+For more information and examples, please refer to the following links:
 
-General guidelines
-------------------
-
-* Any non-trivial change must contain tests
-* All the functions and methods must contain Sphinx docstrings which are used
-  to generate API documentation. You can find a lot of examples of docstrings
-  in the existing code e.g. - ``libcloud/compute/base.py``
-* If you are adding a new feature, make sure to add corresponding documentation
+* Sphinx Documentation - http://sphinx-doc.org/markup/desc.html#info-field-lists
+* Example Libcloud module with documentation - https://github.com/apache/libcloud/blob/trunk/libcloud/compute/base.py
 
 Contribution workflow
 ---------------------


Mime
View raw message