Commits

George Notaras committed 879cfb2

Written help notes in reStructuredText

Comments (0)

Files changed (1)

 django-recaptcha-works Help
-========================================================================
+===========================
 This file contains detailed information on how to configure and use
 ``django-recaptcha-works``.
 
 
 reCaptcha Service
 =================
-In order to use this app you need a valid reCaptcha key pair, which can
-be obtained for free from:
+In order to use this application you need a valid reCaptcha key pair, which
+can be obtained for free from::
 
-  http://www.google.com/recaptcha
+    http://www.google.com/recaptcha
 
  
 Installation
 ============
+In your Django project’s settings module, add ``recaptcha_works`` to your
+``INSTALLED_APPS`` setting::
 
-Add it to the INSTALLED_APPS in settings.py:
-
-INSTALLED_APPS = (
-    ...
-    'recaptcha_works',
-)
+    INSTALLED_APPS = (
+        ...
+        'recaptcha_works',
+    )
 
 
 Configuration
 =============
-The recaptcha_works app accepts the following configuration options:
+The ``recaptcha_works`` application accepts the following configuration
+options:
 
-RECAPTCHA_PUBLIC_KEY: The public key as obtained from google.com/recaptcha
+RECAPTCHA_PUBLIC_KEY
+  The public key as obtained from *google.com/recaptcha*
 
-RECAPTCHA_PRIVATE_KEY: The private key as obtained from google.com/recaptcha
+RECAPTCHA_PRIVATE_KEY
+  The private key as obtained from *google.com/recaptcha*
 
-RECAPTCHA_USE_SSL: True/False -- Enables/disables secure communication with
-the recaptcha servers.
+RECAPTCHA_USE_SSL
+  Boolean setting (``True``/``False``). Enables/disables secure communication
+  with the recaptcha servers.
 
-RECAPTCHA_OPTIONS: A dictionary with the recaptcha customization options.
-Read the following page for more information:
-  - http://code.google.com/apis/recaptcha/docs/customization.html
+RECAPTCHA_OPTIONS
+  A dictionary with the recaptcha customization options.
+  Read the following page for more information:
+  http://code.google.com/apis/recaptcha/docs/customization.html
 
-RECAPTCHA_VALIDATION_OVERRIDE: This is a boolean setting which makes it possible
-to override the validation of the reCaptcha field. This is meant to be enabled
-only when testing your application's reCaptcha-protected forms. Note that
-this is a global switch which, when enabled, overrides validation of the
-reCaptcha field on all reCaptcha-protected forms. To override the validation
-on a single form, set the ``required=False`` attribute on the reCaptcha field
-on that specific form.
+RECAPTCHA_VALIDATION_OVERRIDE
+  Boolean setting (``True``/``False``). By default, this is set to ``False``.
+  When set to ``True``, the reCaptcha field validation is overridden. This
+  setting is not meant to be enabled in production, but only for application
+  testing. Also, note that this is a **global switch**, which, when enabled,
+  overrides validation of the reCaptcha field on all reCaptcha-protected forms.
+  To override the validation on a single form, set the ``required=False``
+  attribute on the reCaptcha field on that specific form.
 
-Example configuration:
+Example configuration for production::
 
-RECAPTCHA_PUBLIC_KEY  = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
-RECAPTCHA_PRIVATE_KEY = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
-RECAPTCHA_USE_SSL = True
-RECAPTCHA_OPTIONS = {
-    'theme': 'white',
-    'lang': 'en',
-    'tabindex': 0,
-}
+    RECAPTCHA_PUBLIC_KEY  = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+    RECAPTCHA_PRIVATE_KEY = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+    RECAPTCHA_USE_SSL = True
+    RECAPTCHA_OPTIONS = {
+        'theme': 'white',
+        'lang': 'en',
+        'tabindex': 0,
+    }
 
 
 Usage
 =====
-recaptcha_works provides a form field which can be attached to your forms.
-Implementing a reCaptcha protected form is a two step process.
+*django-recaptcha-works* provides a form field which can be attached to your
+forms. Implementing a reCaptcha protected form is a *two step* process.
 
-Step 1: Create the reCaptcha protected form:
+**Step 1**: Create the reCaptcha protected form::
 
     from django import forms
     from recaptcha_works.fields import RecaptchaField
         # ... other form fields
         recaptcha = RecaptchaField(label='Human test', required=True)
 
-Step 2: Use the ``fix_recaptcha_remote_ip`` decorator around the view that
+**Step 2**: Use the ``fix_recaptcha_remote_ip`` decorator around the view that
 processes the form data. This is required because the remote IP is a mandatory
 argument for the verification of the information the user has submitted in the
 reCaptcha field, but it cannot be added to the form field automatically due to
-limitations of the Django framework.
+limitations of the Django framework::
 
     from recaptcha_works.decorators import fix_recaptcha_remote_ip