Update misc section. Refs #315

diff --git a/README.rst b/README.rst
index 8a0857285b07405a637325b58c250986ca6f30a6..90a0c1f594a1d7eb9e7a885413430994f8af8b95 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -961,20 +961,44 @@ Some particular use cases are listed below.
 Miscellaneous
 -------------
 
+Mailing list
+^^^^^^^^^^^^
 Join to `django-social-auth discussion list`_ and bring any questions or suggestions
 that would improve this application. Convore_ discussion group is deprecated since
 the service is going to be shut down on April 1st.
 
-If defining a custom user model, do not import social_auth from any models.py
-that would finally import from the models.py that defines your User class or it
-will make your project fail with a recursive import because social_auth uses
-get_model() to retrieve your User.
-
+Sout users
+^^^^^^^^^^
+South_ users should add this rule to enable migrations::
+
+    try:
+        import south
+        from south.modelsinspector import add_introspection_rules
+        add_introspection_rules([], ["^social_auth\.fields\.JSONField"])
+    except:
+        pass
+
+Custom User model
+^^^^^^^^^^^^^^^^^
+If defining a custom user model, do not import ``social_auth`` from any
+``models.py`` that would finally import from the ``models.py`` that defines
+your ``User`` class or it will make your project fail with a recursive import
+because ``social_auth`` uses ``get_model()`` to retrieve your User.
+
+Third party backends
+^^^^^^^^^^^^^^^^^^^^
 There's an ongoing movement to create a list of third party backends on
 djangopackages.com_, so, if somebody doesn't want it's backend in the
 ``contrib`` directory but still wants to share, just split it in a separated
 package and link it there.
 
+Python 2.7.2rev4, 2.7.3 and Facebook backend
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Seems that this bug described in StackOverflow_ hits users using
+django-social-auth_ with Python versions 2.7.2rev4 and 2.7.3 (so far) and
+Facebook backend. The bug report `#315`_ explains it a bit more and shows
+a workaround fit avoid it.
+
 Bugs
 ----
 
@@ -1115,3 +1139,5 @@ Base work is copyrighted by:
 .. _Instagram API: http://instagr.am/developer/
 .. _django-social-auth discussion list: https://groups.google.com/group/django-social-auth
 .. _Twitter OAuth keys: https://dev.twitter.com/docs/auth/authorizing-request
+.. _StackOverflow: http://stackoverflow.com/questions/9835506/urllib-urlopen-works-on-sslv3-urls-with-python-2-6-6-on-1-machine-but-not-wit
+.. _#315: https://github.com/omab/django-social-auth/issues/315

diff --git a/doc/miscellaneous.rst b/doc/miscellaneous.rst
index ce0ee677baa4c3e26c2e1c0e69538a93b11f3ca9..8933631c38b018d2490153bba6edfa47534d472b 100644 (file)
--- a/doc/miscellaneous.rst
+++ b/doc/miscellaneous.rst
@@ -1,10 +1,17 @@
 Miscellaneous
 =============
 
+Mailing list
+------------
+
 Join to `django-social-auth discussion list`_ and bring any questions or suggestions
 that would improve this application. Convore_ discussion group is deprecated since
 the service is going to be shut down on April 1st.
 
+
+Sout users
+----------
+
 South_ users should add this rule to enable migrations::
 
     try:
@@ -14,10 +21,18 @@ South_ users should add this rule to enable migrations::
     except:
         pass
 
-If defining a custom user model, do not import social_auth from any models.py
-that would finally import from the models.py that defines your User class or it
-will make your project fail with a recursive import because social_auth uses
-get_model() to retrieve your User.
+
+Custom User model
+-----------------
+
+If defining a custom user model, do not import ``social_auth`` from any
+``models.py`` that would finally import from the ``models.py`` that defines
+your ``User`` class or it will make your project fail with a recursive import
+because ``social_auth`` uses ``get_model()`` to retrieve your User.
+
+
+Third party backends
+--------------------
 
 There's an ongoing movement to create a list of third party backends on
 djangopackages.com_, so, if somebody doesn't want it's backend in the
@@ -25,8 +40,20 @@ djangopackages.com_, so, if somebody doesn't want it's backend in the
 package and link it there.
 
 
+Python 2.7.2rev4, 2.7.3 and Facebook backend
+-------------------------------------------
+
+Seems that this bug described in StackOverflow_ hits users using
+django-social-auth_ with Python versions 2.7.2rev4 and 2.7.3 (so far) and
+Facebook backend. The bug report `#315`_ explains it a bit more and shows
+a workaround fit avoid it.
+
+
+
 .. _South: http://south.aeracode.org/
 .. _django-social-auth: https://github.com/omab/django-social-auth
 .. _Convore: https://convore.com/
 .. _djangopackages.com: http://djangopackages.com/grids/g/social-auth-backends/
 .. _django-social-auth discussion list: https://groups.google.com/group/django-social-auth
+.. _StackOverflow: http://stackoverflow.com/questions/9835506/urllib-urlopen-works-on-sslv3-urls-with-python-2-6-6-on-1-machine-but-not-wit
+.. _#315: https://github.com/omab/django-social-auth/issues/315