Documentation wtf :)

docs/_static/djangodocs.css

@@ -49,7 +49,7 @@ h4 { font-size:125%; font-weight:bold; margin-top:1.5em; margin-bottom:3px}
 div.figure { text-align: center}
 div.figure p.caption { font-size:1em; margin-top:0; margin-bottom:1.5em; color: black}
 hr { color:#ccc; background-color:#ccc; height:1px; border:0}
-p, ul, dl { margin-top:.6em; margin-bottom:1em; padding-bottom: 0.1em; color: #333}
+p, ul, dl { margin-top:.6em; margin-bottom:1em; color: #333}
 #yui-main div.yui-b img { max-width: 50em; margin-left: auto; margin-right: auto; display: block}
 caption { font-size:1em; font-weight:bold; margin-top:0.5em; margin-bottom:0.5em; margin-left: 2px; text-align: center}
 blockquote { padding: 0 1em; margin: 1em 0; font:125%/1.2em "Trebuchet MS", sans-serif; color:#234f32}
@@ -61,7 +61,7 @@ ins { font-weight: bold; text-decoration: none}
 ul { padding-left:30px}
 ol { padding-left:30px}
 ol.arabic li { list-style-type: decimal}
-ul li { list-style-type:square; margin-bottom:.4em; font-size: 14px}
+ul li { list-style-type:square; font-size: 14px}
 ol li { margin-bottom: .4em}
 ul ul { padding-left:1.2em}
 ul ul ul { padding-left:1em}

docs/index.rst

@@ -48,21 +48,32 @@ Quickstart
 
    user@machine:~/Projects/my-project$ lettuce features/
 
-First steps
-===========
+Introduction
+============
 
     * **What is Lettuce, and what it does:**
 
       * :ref:`Overview <intro-overview>`
       * :ref:`Installation <intro-install>`
 
+What the feature ?!
+-------------------
+
+      :ref:`Understand the terms behind Lettuce <intro-wtf>`
+
+Walkthrough
+===========
+
     * **Tutorial:**
 
-      * :ref:`Simple features <tutorial-simple>`
+      * :ref:`Using simple features <tutorial-simple>`
       * :ref:`Steps with tables <tutorial-tables>`
       * :ref:`Scenario Outlines <tutorial-scenario-outlines>`
       * :ref:`Taking actions before and after tests <tutorial-hooks>`
 
+Furthermore
+===========
+
     * **Reference and concepts:**
 
       * :ref:`Features <reference-features>`

docs/intro/overview.rst

@@ -33,6 +33,15 @@ is a honking great tool, and has a lot more features than Lettuce.
 Although Lettuce aims on the most usual tasks on BDD_, specially
 focusing on those that make BDD_ be so fun :)
 
+Lettuce pragma
+==============
+
+Give to developers ability to describe :ref:`features <intro-wtf>` in
+natural language, composing it with one one or more scenarios.
+
+Each scenario has one possible behaviour of the feature you want to implement.
+To make the scenarios run python code, you define :ref:`steps <reference-steps`.
+
 Comparation with other BDD tools
 ================================
 

docs/intro/wtf.rst

+.. _intro-wtf:
+
+=====================
+What the f** eature ?
+=====================
+
+Unless you are used to Cucumber_ nomenclature, you may be wondering
+about the terms that surround Lettuce concepts.
+
+If this is your case, this introduction will guide you through the
+very basic keywords that concept Lettuce.
+
+
+Features
+========
+
+Since Lettuce is based on the *behaviour* of the project that is being
+designed, you will think on features.
+
+After enumerating features, you will create scenarios to describe its
+feature. Thus, scenarios are components of a feature.
+
+Let's learn by example, supposing we want to create a system to manage
+a contact book.
+
+OK, one of the very basic feature of a contact book is adding names
+and phones of a person.
+
+See how this feature could be described with Lettuce above:
+
+::
+
+    Feature: Add people to contact book
+      In order to organize phones of friends
+      As a wise person
+      I want to add a people to my contact book
+
+      Scenario: Add a person with name and phone
+        Given I fill the field "name" with "John"
+        And fill the field "phone" with "2233-4455"
+        When I save the data
+        Then I see that my contact book has the persons:
+          | name | phone     |
+          | John | 2233-4455 |
+
+      Scenario: Avoiding a invalid phone number
+        Given I fill the field "name" with "John"
+        And fill the field "phone" with "000"
+        When I save the data
+        Then I get the error: "000 is a invalid phone number"
+
+In the feature above we can notice a few elements, for instance:
+
+ * The feature name:
+
+ ::
+
+  Feature: Add people to contact book
+
+ * Feature headline:
+
+ ::
+
+     In order to organize phones of friends
+     As a wise person
+     I want to add a people to my contact book
+
+ * Scenarios:
+
+ ::
+
+     Scenario: Add a person with name and phone
+       Given I fill the field "name" with "John"
+       And fill the field "phone" with "2233-4455"
+       When I save the data
+       Then I see that my contact book has the persons:
+         | name | phone     |
+         | John | 2233-4455 |
+
+     Scenario: Avoiding a invalid phone number
+       Given I fill the field "name" with "John"
+       And fill the field "phone" with "000"
+       When I save the data
+       Then I get the error: "000 is a invalid phone number"
+
+Scenarios
+=========
+
+One or more scenarios compose a feature. And there are two kinds of scenarios:
+
+Simple
+~~~~~~
+
+The simple scenarios are composed by steps, no matter if they are
+simple or tabulated steps.
+
+The feature above is composed by two simple scenarios.
+
+Outlined
+~~~~~~~~
+
+Outlined scenarios are very handy and avoid repetition.
+
+Supposing that we need fill the same formulary many times, each time
+with a different data set.
+
+Let's see how it could be done with scenario outlines:
+
+::
+
+    Feature: Apply all my friends to attend a conference
+      In order to apply all my friends to the next PyCon_
+      As a lazy person
+      I want to fill the same form many times
+
+      Scenario Outline: Apply my friends
+        Go to the conference website
+        Access the link "I will attend"
+        Fill the field "name" with "<friend_name>"
+        Fill the field "email" with "<friend_email>"
+        Fill the field "birthday" with "<friend_birthdate>"
+        Click on "confirm attendance" button
+
+      Examples:
+        | friend_name | friend_email         | friend_birthdate |
+        | Mary        | mary@domain.com      | 1988/02/10       |
+        | Lincoln     | lincoln@provider.net | 1987/09/10       |
+        | Marcus      | marcus@other.org     | 1990/10/05       |
+
+In a nutshell, the scenario above is equivalent to write this amount of text:
+
+::
+
+    Feature: Apply all my friends to attend a conference
+      In order to apply all my friends to the next PyCon_
+      As a lazy person
+      I want to fill the same form many times
+
+      Scenario: Apply Mary
+        Go to the conference website
+        Access the link "I will attend"
+        Fill the field "name" with "Mary"
+        Fill the field "email" with "mary@domain.com"
+        Fill the field "birthday" with "1988/02/10"
+        Click on "confirm attendance" button
+
+      Scenario: Apply Lincoln
+        Go to the conference website
+        Access the link "I will attend"
+        Fill the field "name" with "Lincoln"
+        Fill the field "email" with "lincoln@provider.net"
+        Fill the field "birthday" with "1987/09/10"
+        Click on "confirm attendance" button
+
+      Scenario: Apply Marcus
+        Go to the conference website
+        Access the link "I will attend"
+        Fill the field "name" with "Marcus"
+        Fill the field "email" with "marcus@other.org"
+        Fill the field "birthday" with "1990/10/05"
+        Click on "confirm attendance" button
+
+As you can notice, scenario outlines are really useful and help you to
+avoid repetition of text and code.
+
+Steps and its definitions
+=========================
+
+Comparable with Scenarios, Steps comes in two kinds:
+
+Simple steps
+~~~~~~~~~~~~
+
+Simple steps are actually simple, they are matched with step
+definitions.
+
+Lettuce considers each line of a scenario as a simple step, the only
+exception is if the first non-blank character of the line is a pipe
+``|``, in this case Lettuce will consider the step as a tabular step.
+
+Example::
+
+    Given I go to the conference website
+
+Tabular steps
+~~~~~~~~~~~~~
+
+Analog to Outlined Scenarios, the tabular steps are very useful, and
+avoid repetition of text.
+
+Tabular steps are specially useful to set up some data set in aa
+scenario, or compare a set of data to results at the end of the
+scenario.
+
+But nothing avoid you to use at your will.
+
+Example::
+
+    Given I have the following contacts in my database
+      | name  | phone      |
+      | John  | 2233-4455  |
+      | Smith | 9988-7766  |
+
+.. _Agile: http://agilemanifesto.org
+.. _Cucumber: http://cukes.info
+.. _Pyccuracy: http://github.com/heynemann/pyccuracy
+.. _TDD: http://en.wikipedia.org/wiki/Test_Driven_Development
+.. _BDD: http://en.wikipedia.org/wiki/Behavior_Driven_Development

docs/tutorial/simple.rst

@@ -15,6 +15,7 @@ So assuming that:
 
 Let's have a ...
 
-A starty start
+A simple start
 ==============
 
+Lettuce is very flexible about where you decide to put your features.