Merge pull request #222 from benoitbryon/doc-dev

Development guidelines: sharing vision and practices

README.md

@@ -22,52 +22,6 @@ Lettuce is a [BDD](http://en.wikipedia.org/wiki/Behavior_Driven_Development) too
 7. I like [nose](http://code.google.com/p/python-nose/), which is a unittest pythonic framework. However, as the project I work on grows, so do the tests, and it becomes harder to understand them.
 8. [lettuce ladies](http://www.lettuceladies.com/) :)
 
-# Dependencies
-
-**you will need to install these dependencies in order to** *hack* **lettuce** :)
-all them are used within lettuce tests
-
-## you could use a virtualenv:
-
-    > mkvirtualenv lettuce
-    > workon lettuce
-    > pip install -r requirements.txt
-
-## or just install manually:
-
-    > sudo pip install -r requirements.txt
-
-## or do it really from scratch:
-
-* [nose](http://code.google.com/p/python-nose/)
-    > [sudo] pip install nose
-* [mox](http://code.google.com/p/pymox/)
-    > [sudo] pip install mox
-* [sphinx](http://sphinx.pocoo.org/)
-    > [sudo] pip install sphinx
-* [lxml](http://codespeak.net/lxml/)
-    > [sudo] pip install lxml
-* [tornado](http://tornadoweb.org/)
-    > [sudo] pip install tornado
-* [django](http://djangoproject.com/)
-    > [sudo] pip install django
-
-# Contributing
-
-1. fork and clone the project
-2. install the dependencies above
-3. run the tests with make:
-    > make unit functional integration doctest
-4. hack at will
-5. commit, push etc
-6. send a pull request
-
-## keep in mind
-
-![your lack of tests if disturbing the force](http://farm3.static.flickr.com/2248/2282734669_a7f431e660_o.jpg)
-
-### that lettuce is a testing software, patches and pull requests must come with automated tests, and if suitable, with proper documentation.
-
 # mailing list
 
 ## for users

docs/contents.rst

@@ -22,6 +22,7 @@ Lettuce documentation contents
    reference/languages
    recipes/nose
    recipes/django-lxml
+   dev/index
 
 Indices, glossary and tables
 ============================

docs/dev/documentation.rst

+#################################
+Contributing to the documentation
+#################################
+
+This documentation uses `Python-sphinx`_. It uses `reStructuredText`_ 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:
+
+.. highlight:: rst
+
+::
+
+  ##################
+  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:: rst
+
+::
+
+  .. 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.
+
+Links and references
+====================
+
+On pages which are quite long, use links and references footnotes with the
+"target-notes" directive. As an example:
+
+.. highlight:: rst
+
+::
+
+  #############
+  Some document
+  #############
+
+  Some text which includes links to `Example website`_ and many other links.
+
+  `Example website`_ can be referenced multiple times.
+
+  (... document content...)
+
+  And at the end of the document...
+
+  **********
+  References
+  **********
+
+  .. target-notes::
+
+  .. _`Example website`: http://www.example.com/
+
+This :doc:`documentation` page uses this syntax.
+
+*******
+Recipes
+*******
+
+Install Sphinx
+==============
+
+`Python-sphinx`_ installation is covered in :doc:`/dev/install`.
+
+In other cases, please refer to `Python-sphinx`_ documentation.
+
+Export documentation to HTML
+============================
+
+.. highlight:: sh
+
+::
+
+  cd docs/
+  make html
+  cd ..
+
+HTML documentation is exported to docs/_build/html/.
+
+**********
+References
+**********
+
+.. target-notes::
+
+.. _`Python-sphinx`: http://sphinx.pocoo.org/
+.. _`reStructuredText`: http://docutils.sourceforge.net/rst.html

docs/dev/index.rst

+######################
+Development guidelines
+######################
+
+Synopsis
+========
+
+1. fork and clone the project: see `lettuce repository at github.com`_
+2. :doc:`/dev/install`
+3. run the tests: see :doc:`/dev/testing`
+4. hack at will
+5. commit, push, etc...
+6. send a pull request
+
+Table of contents
+=================
+
+.. toctree::
+   :maxdepth: 3
+
+   install
+   testing
+   documentation
+
+Keep in mind
+============
+
+.. image:: http://farm3.static.flickr.com/2248/2282734669_a7f431e660_o.jpg
+   :alt: your lack of tests if disturbing the force
+
+**that lettuce is a testing software, patches and pull requests must come with
+automated tests, and if suitable, with proper documentation.**
+
+References
+==========
+
+.. target-notes::
+
+.. _`lettuce repository at github.com`:
+   https://github.com/gabrielfalcao/lettuce

docs/dev/install-debian-squeeze.rst

+##############################
+Installation on Debian Squeeze
+##############################
+
+Recipe to get a development environment for lettuce in a fresh install of
+Debian Squeeze.
+
+Variables
+=========
+
+The following values are used below. You may customize them depending on your
+needs.
+
+.. highlight:: bash
+
+::
+
+  # Lettuce installation directory.
+  lettuce_dir=~/lettuce
+  # Virtualenv directory.
+  lettuce_env_dir=$lettuce_dir
+  # Git.
+  upstream_url="https://github.com/gabrielfalcao/lettuce.git"
+  fork_url=$upstream_url
+  # System's package manager.
+  system-install() { su -c "aptitude install ${*}" }
+
+Install system dependencies
+===========================
+
+Execute the following commands:
+
+.. highlight:: bash
+
+::
+
+  system-install python-dev python-virtualenv git libxml2-dev libxslt-dev
+
+Get sources
+===========
+
+.. highlight:: bash
+
+::
+
+  git clone $fork_url $lettuce_dir
+  # Configure upstream
+  cd $lettuce_dir
+  git remote add upstream $upstream_url
+
+Create virtualenv
+=================
+
+.. highlight:: bash
+
+::
+
+  virtualenv --distribute --no-site-packages $lettuce_env_dir
+  source $lettuce_env_dir/bin/activate
+  cd $lettuce_dir
+  pip install -r requirements.txt
+
+Install lettuce in develop mode
+===============================
+
+.. highlight:: bash
+
+::
+
+  python setup.py develop
+
+Check installation
+==================
+
+You should be able to run lettuce and tests.
+
+.. highlight:: bash
+
+::
+
+  lettuce --help
+
+Done!
+=====
+
+Go back to :doc:`/dev/index` and learn about :doc:`/dev/testing`.

docs/dev/install.rst

+#############################################
+Install a development environment for lettuce
+#############################################
+
+Here are guidelines to get a development environment for lettuce.
+
+***********
+OS specific
+***********
+
+Here are repcipes for specific operating systems. They should help you go fast
+or automate lettuce installation procedure:
+
+.. toctree::
+
+   install-debian-squeeze
+
+******************
+Generic guidelines
+******************
+
+Dependencies
+============
+
+**you will need to install these dependencies in order to** *hack* **lettuce**
+:)
+
+All of them are used within lettuce tests.
+
+you could use a virtualenv
+--------------------------
+
+.. highlight:: bash
+
+::
+
+  mkvirtualenv lettuce
+  workon lettuce
+  pip install -r requirements.txt
+
+or just install manually
+------------------------
+
+.. highlight:: bash
+
+::
+
+  sudo pip install -r requirements.txt
+
+or do it really from scratch
+----------------------------
+
+* [nose](http://code.google.com/p/python-nose/)
+    > [sudo] pip install nose
+* [mox](http://code.google.com/p/pymox/)
+    > [sudo] pip install mox
+* [sphinx](http://sphinx.pocoo.org/)
+    > [sudo] pip install sphinx
+* [lxml](http://codespeak.net/lxml/)
+    > [sudo] pip install lxml
+* [tornado](http://tornadoweb.org/)
+    > [sudo] pip install tornado
+* [django](http://djangoproject.com/)
+    > [sudo] pip install django
+
+Installing lettuce itself
+=========================
+
+.. highlight:: bash
+
+::
+
+  [sudo] python setup.py develop

docs/dev/testing.rst

+#######
+Testing
+#######
+
+How to run and write tests for lettuce.
+
+*********
+Run tests
+*********
+
+.. highlight:: bash
+
+::
+
+  make unit functional integration doctest

docs/index.rst

@@ -75,6 +75,10 @@ Fork it, propose features, explore the code
 
 * `lettuce development mailing list <http://groups.google.com/group/lettuce-developers>`_.
 
+**hack**
+
+:doc:`/dev/index`
+
 **donate**
 
 `support lettuce development <http://pledgie.com/campaigns/10604>`_