Merge pull request #28 from doismellburning/feature/docstring-all-the…

…-things

Docstring all the things

django12factor/__init__.py

@@ -1,3 +1,11 @@
+"""
+django12factor: Bringing 12factor configuration to Django.
+
+* http://12factor.net/
+* http://12factor.net/config
+* https://github.com/doismellburning/django12factor
+"""
+
 import django_cache_url
 import dj_database_url
 import dj_email_url
@@ -15,6 +23,17 @@
 
 
 def getenv_bool(setting_name):
+    """
+    Get a boolean from an environment variable.
+
+    Why use this and not just `bool(os.getenv("X"))`?  It would be quite
+    reasonable to see `DEBUG=true`, and infer that setting `DEBUG=false` would
+    Do The Right Thing; however `bool("false") == True`.
+
+    This function attempts to do basic "is the string falsey" detection so
+    `DEBUG=false` behaves as expected
+    """
+
     if setting_name not in os.environ:
         return False
 

tests/env.py

@@ -2,6 +2,15 @@
 
 
 class Env(object):
+    """
+    Test helper providing temporary environments.
+
+    Usage:
+
+        with Env(DEBUG="true"):
+            d = django12factor.factorise()
+    """
+
     def __init__(self, **kwargs):
         self.environ = kwargs
 

tox.ini

@@ -30,4 +30,4 @@ commands =
 
 [testenv:pep257]
 commands =
-	pep257 --ignore D100,D101,D102,D103,D200,D202,D203 django12factor tests
+	pep257 --ignore D200,D202,D203 django12factor