Merge pull request #160 from chris-morgan/master^^^^^

A few more docs improvements

docs/recipes/django-lxml.rst

@@ -117,7 +117,7 @@ Once you install the ``lettuce.django`` app, the command ``harvest`` will be ava
 5. specifying feature files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The `harvest` command accepts a path to feature files, in order to run
+The ``harvest`` command accepts a path to feature files, in order to run
 only the features you want.
 
 Example:
@@ -258,7 +258,7 @@ Running without HTTP server
 
 Sometimes you may just do not want to run Django's built-in HTTP server
 running in background, in those cases all you need to do is run the
-`harvest` command with the `--no-server` or `-S` option.
+``harvest`` command with the ``--no-server`` or ``-S`` option.
 
 Example:
 
@@ -275,7 +275,7 @@ running the HTTP server in other port than 8000
 If you face the problem of having lettuce running on port 8000, you
 can change that behaviour.
 
-Before running the server, lettuce will try to read the setting `LETTUCE_SERVER_PORT` which **must** be a **integer**
+Before running the server, lettuce will try to read the setting ``LETTUCE_SERVER_PORT`` which **must** be a **integer**
 
 Example:
 
@@ -296,7 +296,7 @@ In order to run tests against the nearest configuration of production,
 lettuce sets up settings.DEBUG=False
 
 However, for debug purposes one can face a misleading HTTP 500 error without traceback in Django.
-For those cases lettuce provides the `--debug-mode` or `-d` option.
+For those cases lettuce provides the ``--debug-mode`` or ``-d`` option.
 
 .. highlight:: bash
 
@@ -309,7 +309,7 @@ running only the specified scenarios
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also specify the index of the scenarios you want to run
-through the command line, to do so, run with `--scenarios` or `-s`
+through the command line, to do so, run with ``--scenarios`` or ``-s``
 options followed by the scenario numbers separated by commas.
 
 For example, let's say you want to run the scenarios 4, 7, 8 and 10:
@@ -331,7 +331,7 @@ running tests from just certain apps
 
 Lettuce takes a comma-separated list of app names to run tests against.
 
-For example, the command below would run ONLY the tests within the apps `myapp` and `foobar`:
+For example, the command below would run ONLY the tests within the apps ``myapp`` and ``foobar``:
 
 .. highlight:: bash
 
@@ -343,7 +343,7 @@ For example, the command below would run ONLY the tests within the apps `myapp`
 
    python manage.py harvest --a  myapp,foobar
 
-You can also specify it at `settings.py` so that you won't need to type the same command-line parameters all the time:
+You can also specify it at ``settings.py`` so that you won't need to type the same command-line parameters all the time:
 
 .. highlight:: python
 
@@ -368,7 +368,7 @@ running tests from all apps, except by some
 
 Lettuce takes a comma-separated list of app names which tests must NOT be ran.
 
-For example, the command below would run ALL the tests BUT those within the apps `another_app` and `foobar`:
+For example, the command below would run ALL the tests BUT those within the apps ``another_app`` and ``foobar``:
 
 .. highlight:: bash
 
@@ -376,7 +376,7 @@ For example, the command below would run ALL the tests BUT those within the apps
 
    python manage.py harvest --avoid-apps=another_app,foobar
 
-You can also specify it at `settings.py` so that you won't need to type the same command-line parameters all the time:
+You can also specify it at ``settings.py`` so that you won't need to type the same command-line parameters all the time:
 
 .. highlight:: python
 

docs/reference/cli.rst

@@ -28,7 +28,7 @@ running a specific feature file
    user@machine:~/projects/myproj$ lettuce path/to/some/file.feature
 
 
-With this option, your feature can even be out of the default ***features*** folder.
+With this option, your feature can even be out of the default ``features`` folder.
 
 running only some scenarios of a specific feature file
 ------------------------------------------------------
@@ -40,7 +40,7 @@ running only some scenarios of a specific feature file
    user@machine:~/projects/myproj$ lettuce path/to/some/file.feature -s 3,5,9
 
 
-This will run the scenarios 3, 5 and 9 from file ***path/to/some/file.feature***
+This will run the scenarios 3, 5 and 9 from file ``path/to/some/file.feature``
 
 running only some scenarios all feature files
 ---------------------------------------------
@@ -55,7 +55,7 @@ Maybe you can find it senseless, but it works like that, and does not hurt so fa
 
 Yeah, guess what?
 
-This command will run the scenarios 3, 5 and 9 of all feature files living on ***myproj/features*** folder.
+This command will run the scenarios 3, 5 and 9 of all feature files living on ``myproj/features`` folder.
 
 verbosity levels
 ----------------
@@ -159,7 +159,7 @@ It prints every single feature, with really useful information like:
 * "ready-to-use" snippets for undefined steps
 
 For example, let's say you have the feature below, but only the step
-***Given I have the string "lettuce leaves"*** is defined
+``Given I have the string "lettuce leaves"`` is defined
 
 .. highlight:: ruby
 

docs/reference/features.rst

@@ -12,7 +12,7 @@ to read :ref:`the feature tutorial <tutorial-simple>` for a
 introduction.
 
 In order to exemplify the usage of attributes and methods below, let's
-consider that there is a feature in a file called `some.feature`
+consider that there is a feature in a file called ``some.feature``
 
 .. highlight:: ruby
 
@@ -52,7 +52,7 @@ Feature.scenarios
 
 A list of scenario objects
 
-The attribute `scenarios` could be used as follows
+The attribute ``scenarios`` could be used as follows
 
 .. highlight:: python
 
@@ -67,7 +67,7 @@ A FeatureDescription object, has the file and line which the feature
 was described. Lettuce uses it to output those metadata.
 
 
-The attribute `described_at` could be used as follows
+The attribute ``described_at`` could be used as follows
 
 ::
 
@@ -125,7 +125,7 @@ But if the same feature would written in Brazilian Portuguese, for example:
           Cenário: ...
             ...
 
-Then, `Feature.get_head()` would give:
+Then, ``Feature.get_head()`` would give:
 
 ::
 
@@ -176,7 +176,7 @@ Scenario.steps
 
 A list of scenario objects
 
-The attribute `scenarios` could be used as follows
+The attribute ``scenarios`` could be used as follows
 
 .. highlight:: python
 

docs/reference/terrain.rst

@@ -11,7 +11,7 @@ setup and teardown, and general hacking on your lettuce tests.
 terrain.py
 ~~~~~~~~~~
 
-By convention lettuce tries do load a file called `terrain.py` located
+By convention lettuce tries do load a file called ``terrain.py`` located
 at the current directory.
 
 Think at this file as a global setup place, there you can setup global
@@ -19,8 +19,8 @@ hooks, and put things into lettuce "world".
 
 .. Note::
 
-   You can also set a `terrain.py` file within the root of your
-   Django_ project, when running the `python manage.py harvest`
+   You can also set a ``terrain.py`` file within the root of your
+   Django_ project, when running the ``python manage.py harvest``
    command, lettuce will load it. See more at
    :ref:`the-django-command`.
 
@@ -39,7 +39,7 @@ Try out this file layout:
                 - the-file-which-holds-step-definitions.py
                 - terrain.py
 
-Then add some setup at `terrain.py` and run lettuce
+Then add some setup at ``terrain.py`` and run lettuce
 
 .. highlight:: bash
 
@@ -48,7 +48,7 @@ Then add some setup at `terrain.py` and run lettuce
    user@machine:~/projects/some-project$ lettuce
 
 
-And notice `terrain.py` will be loaded before anything
+And notice ``terrain.py`` will be loaded before anything
 
 .. _lettuce-world:
 
@@ -75,7 +75,7 @@ application before lettuce start running tests:
 
    world.some_variable = "yay!"
 
-So that, within some step file you could use things previously set on `world`:
+So that, within some step file you could use things previously set on ``world``:
 
 
 .. doctest::
@@ -367,7 +367,7 @@ can be very useful for setting up browser drivers (such as selenium),
 before all tests start to run on Django.
 
 The decorated function takes a dict with the local variables within
-the `harvest` management command.
+the ``harvest`` management command.
 
 .. doctest::
 
@@ -443,7 +443,7 @@ The decorated function takes two arguments:
 
 These hooks are ran right before, and after lettuce starts up the built-in http server.
 
-The decorated function takes a `lettuce.django.server.ThreadedServer` object.
+The decorated function takes a ``lettuce.django.server.ThreadedServer`` object.
 
 .. doctest::
 
@@ -468,8 +468,8 @@ These hooks are ran right before, and after lettuce's built-in HTTP server respo
 
 Both decorated functions takes these two arguments:
 
-* a `django.core.servers.basehttp.WSGIServer` object.
-* a `lettuce.django.server.ThreadedServer` object.
+* a ``django.core.servers.basehttp.WSGIServer`` object.
+* a ``lettuce.django.server.ThreadedServer`` object.
 
 .. doctest::
 
@@ -486,7 +486,7 @@ Both decorated functions takes these two arguments:
        socket_object, (client_address, size) = httpd.get_request()
        print "I've just finished to respond to the client %s" % client_address
 
-.. warning:: all the `handle_request` hooks are run within a python
+.. warning:: all the ``handle_request`` hooks are run within a python
    thread. If something went wrong within a calback, lettuce can get
    stuck.
 

docs/tool-comparation.txt

-.. _tool-comparation:
-
-This is not the first time I write a tool for
-behaviour-driven development. I worked on Pyccuracy_ which is a
-awesome tool for testing websites.
-
-And as expected I am a hard user of Pyccuracy_, but since I met
-Cucumber_, I fell in love for Scenario Outlines, global variables and
-tables.  Although Pyccuracy_ does not aim to do the same that Cucumber_
-does, sometimes it sucks, because Cucumber has very handy features, that
-avoid code duplicity and so on.
-
-Thus, Lettuce does not aim on website automated testing, Lettuce is a
-multi-purpose testing tool.
-
-.. _Agile: http://agilemanifesto.org/
-.. _Cucumber: http://cukes.info
-.. _Pyccuracy: http://github.com/heynemann/pyccuracy

docs/tool-comparisons.txt

+.. _tool-comparisons:
+
+This is not the first time I have written a tool for
+behaviour-driven development. I worked on Pyccuracy_ which is an
+awesome tool for testing websites.
+
+As expected I am a hard user of Pyccuracy_, but since I met
+Cucumber_, I fell in love with Scenario Outlines, global variables and
+tables.  Although Pyccuracy_ does not aim to do the same as Cucumber_
+does, sometimes it sucks, because Cucumber has very handy features that
+avoid code duplication and so on.
+
+Thus, Lettuce does not aim solely at automated website testing. Lettuce
+is a multi-purpose testing tool.

docs/tutorial/scenario-outlines.rst

@@ -3,7 +3,7 @@
 scenario outlines
 =================
 
-On our :ref:`first description file<tutorial-simple>`, `zero.feature`, all scenarios were
+On our :ref:`first description file<tutorial-simple>`, ``zero.feature``, all scenarios were
 similar. This made us repeat most of the text again and again.
 
 **Isn't there a better way to deal with this - when several scenarios are almost equal and only some values change?**

docs/tutorial/simple.rst

@@ -42,7 +42,7 @@ Let's choose a problem to lettuce:
 project structure
 =================
 
-Build the directory tree bellow such as the files `zero.feature` and `steps.py` are empty.
+Build the directory tree bellow such as the files ``zero.feature`` and ``steps.py`` are empty.
 
 .. highlight:: bash
 
@@ -66,7 +66,7 @@ first round
 [a] describe behaviour
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Start describing the expected behaviour of factorial in `zero.feature` using English:
+Start describing the expected behaviour of factorial in ``zero.feature`` using English:
 
 .. highlight:: ruby
 
@@ -91,7 +91,7 @@ Start describing the expected behaviour of factorial in `zero.feature` using Eng
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Now let's define the steps of the scenario, so Lettuce can
-understand the behaviour description. Create the `steps.py` file which will contain 
+understand the behaviour description. Create the ``steps.py`` file which will contain 
 python code describing the steps.
 
 Python:
@@ -121,8 +121,8 @@ Python:
 
 .. Note::
 
-   `steps.py` must be inside features directory, but the names doesn't
-   need to be `steps.py` it can be any python file with a `.py` extension.
+   ``steps.py`` must be inside features directory, but the names doesn't
+   need to be ``steps.py`` it can be any python file with a ``.py`` extension.
    Lettuce_ will look for python files recursively within features
    dir.
 

docs/tutorial/steps-from-step-definitions.rst

@@ -28,7 +28,7 @@ In this case, we probably had a test case (maybe several) for which it was actua
       When I do something interesting
       Then The world becomes a better place
       
-Lettuce affords you the ability to write such a "step of steps" with a set of helpers matching each of the grammar terms `Given`, `When` and `Then`. You could accomplish the above like so.
+Lettuce affords you the ability to write such a "step of steps" with a set of helpers matching each of the grammar terms ``Given``, ``When`` and ``Then``. You could accomplish the above like so.
 
 .. highlight:: python
 
@@ -43,7 +43,7 @@ Lettuce affords you the ability to write such a "step of steps" with a set of he
 running blocks of steps
 -----------------------
 
-It is sometimes even desirable to run blocks of steps, copy-and-pasted directly from Feature specifications. The `Step.behave_as` method lets you do this, and you can use `string.format` to fill in parameters dynamically. For example, we can write the above step definition like so:
+It is sometimes even desirable to run blocks of steps, copy-and-pasted directly from Feature specifications. The ``Step.behave_as`` method lets you do this, and you can use ``str.format`` to fill in parameters dynamically. For example, we can write the above step definition like so:
 
 .. highlight:: python
 
@@ -54,11 +54,8 @@ It is sometimes even desirable to run blocks of steps, copy-and-pasted directly
         step.behave_as("""
             Given I go to the home page
               And I click the login button
-              And I fill in username:%(user)s password:%(pass)s
+              And I fill in username:{user} password:{pass}
               And I click "Login"
-        """.format({
-            'user': 'floppy',
-            'pass': 'banana'
-        }))
+        """.format(user='floppy', pass='banana'))
 
 This can be combined with step argument capture for step definitions that are both expressive and DRY.