This file contains detailed information on how to configure and use
-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::
+In your Django project’s settings module, add ``recaptcha_works`` to your
-Add it to the INSTALLED_APPS in settings.py:
-The recaptcha_works app accepts the following configuration options:
+The ``recaptcha_works`` application accepts the following configuration
-RECAPTCHA_PUBLIC_KEY: The public key as obtained from google.com/recaptcha
+ The public key as obtained from *google.com/recaptcha*
-RECAPTCHA_PRIVATE_KEY: The private key as obtained from google.com/recaptcha
+ The private key as obtained from *google.com/recaptcha*
-RECAPTCHA_USE_SSL: True/False -- Enables/disables secure communication with
+ 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
+ A dictionary with the recaptcha customization options.
+ Read the following page for more information:
-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
+ 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.
-RECAPTCHA_PUBLIC_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
-RECAPTCHA_PRIVATE_KEY = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
-RECAPTCHA_USE_SSL = True
+ RECAPTCHA_PUBLIC_KEY = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
+ RECAPTCHA_PRIVATE_KEY = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'
+ RECAPTCHA_USE_SSL = True
-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 recaptcha_works.fields import RecaptchaField
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