Fix mozilla#64: Add docs for CSP issues.

docs/details/troubleshooting.rst

@@ -0,0 +1,22 @@
+Troubleshooting
+===============
+
+CSP WARN: Directive "..." violated by https://browserid.org/include.js
+----------------------------------------------------------------------
+
+This warning appears in the Error Console when your site uses 
+`Content Security Policy`_ without making an exception for the browserid.org
+external JavaScript include.
+
+To fix this, include https://browserid.org in your script-src directive. If 
+you're using the `django-csp`_ library, the following settings will work::
+
+    CSP_SCRIPT_SRC = ("'self'", 'https://browserid.org',)
+    CSP_FRAME_SRC = ("'self'", 'https://browserid.org',)
+
+.. note:: The example above also includes the frame-src directive. There is an
+   iframe used during BrowserID login, but some people report that login will
+   work without the directive. In general, you should probably include it.
+
+.. _Content Security Policy: https://developer.mozilla.org/en/Security/CSP
+.. _django-csp: https://github.com/mozilla/django-csp

docs/index.rst

@@ -22,3 +22,4 @@ to fork_ and contribute!
    setup
    details/customization
    details/settings
+   details/troubleshooting

docs/setup.rst

@@ -97,5 +97,16 @@ This JavaScript file requires jQuery.
       <script src="https://browserid.org/include.js"></script>
       <!-- Include JS for browserid_form here. -->
 
+.. note:: If your site uses `Content Security Policy`_, you will have to add
+   directives to allow the external browserid.org JavaScript, as well as an
+   iframe used as part of the login process.
+
+   If you're using `django-csp`_, the following settings will work::
+
+      CSP_SCRIPT_SRC = ("'self'", 'https://browserid.org',)
+      CSP_FRAME_SRC = ("'self'", 'https://browserid.org',)
+
 .. _Form Media: https://docs.djangoproject.com/en/1.3/topics/forms/media/
 .. _Managing static files: https://docs.djangoproject.com/en/1.3/howto/static-files/
+.. _Content Security Policy: https://developer.mozilla.org/en/Security/CSP
+.. _django-csp: https://github.com/mozilla/django-csp