Updated casts docs section (#23)

* Updated casts docs section

* Removed --quiet arg since it's breaking the build

.ci/deps.osx.sh

@@ -3,7 +3,7 @@ set -x
 
 # Install packages with brew
 brew update >/dev/null
-brew outdated pyenv || brew upgrade --quiet pyenv
+brew outdated pyenv || brew upgrade pyenv
 
 # Install required python version for this build
 pyenv install -ks $PYTHON_VERSION

docs/source/casts.rst

@@ -0,0 +1,64 @@
+Casts
+-----
+
+Buitin Casts
+~~~~~~~~~~~~
+
+#. ``config.boolean`` - converts values like ``On|Off``, ``1|0``, ``yes|no``,
+   ``true|false`` into booleans.
+#. ``config.eval`` - safely evaluate strings with Python literals to Python
+   objects (alias to Python's ``ast.literal_eval``).
+#. ``config.list`` - converts comma separated strings into lists.
+#. ``config.tuple`` - converts comma separated strings into tuples.
+#. ``config.option`` - get a return value based on specific options:
+
+.. code-block:: python
+
+    environments = {
+        "production": ("spam", "eggs"),
+        "local": ("spam", "eggs", "test"),
+    }
+
+    # Will return a tuple with ("spam", "eggs") when
+    # ENVIRONMENT is undefined or defined with `production`
+    # and a tuple with ("spam", "eggs", "test") when
+    # ENVIRONMENT is set with `local`.
+    MODULES = config("ENVIRONMENT",
+                     default="production",
+                     cast=Option(environment))
+
+
+Custom casts
+~~~~~~~~~~~~
+
+You can implement your own custom casting function:
+
+.. code-block:: python
+
+   def number_list(value):
+       return [int(v) for v in value.split(";")]
+
+   NUMBERS = config("NUMBERS", default="1;2;3", cast=number_list)
+
+
+Useful third-parties casts
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django is a popular python web framework that imposes some structure on the way
+its settings are configured. Here are a few 3rd party casts that help you adapt
+strings into that inner structures:
+
+* `dj-database-url`_ - Parses URLs like ``mysql://user:pass@server/db`` into
+  Django ``DATABASES`` configuration format.
+* `django-cache-url`_ - Parses URLs like ``memcached://server:port/prefix``
+  into Django ``CACHES`` configuration format.
+* `dj-email-url`_ - Parses URLs like
+  ``smtp://[email protected]:[email protected]:465/?ssl=True`` with
+  parameters used in Django ``EMAIL_*`` configurations.
+* `dj-admins-setting`_ - Parses emails lists for the ``ADMINS`` configuration.
+
+
+.. _dj-database-url: https://github.com/kennethreitz/dj-database-url
+.. _django-cache-url: https://github.com/ghickman/django-cache-url
+.. _dj-email-url: https://github.com/migonzalvar/dj-email-url
+.. _dj-admins-setting: https://github.com/hernantz/dj-admins-setting

docs/source/faq.rst

@@ -76,8 +76,8 @@ See the lookup order of configurations below
 .. _contributions: https://github.com/henriquebastos/python-decouple/pull/5
 
 
-How does prettyconf compare to python-dotenv?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+How does prettyconf compare to python-dotenv_?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 python-dotenv_ reads the key, value pair from .env file and adds them to
 environment variable. It is good for some tools that simply proxy the env to

docs/source/index.rst

@@ -14,6 +14,7 @@ Contents:
    introduction.rst
    installation.rst
    usage.rst
+   casts.rst
    advanced.rst
    loaders.rst
    faq.rst

docs/source/usage.rst

@@ -32,6 +32,10 @@ a specific value type:
 The ``boolean`` cast converts strings values like ``On|Off``, ``1|0``,
 ``yes|no``, ``true|False`` into Python boolean ``True`` or ``False``.
 
+.. seealso::
+    Find out more about other casts or how to write
+    your own at :doc:`Casts<casts>`.
+
 
 Configuration files discovery
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -56,64 +60,3 @@ start looking for configuration files at ``project/app`` until it finds
     :py:class:`RecursiveSearch<prettyconf.loaders.RecursiveSearch>` loader.
     :doc:`Loaders<loaders>` will help you customize how configuration
     discovery works. Find out more at :ref:`discovery-customization`.
-
-
-Casts
-~~~~~
-
-Buitin Casts
-++++++++++++
-
-#. ``config.boolean`` - converts values like ``On|Off``, ``1|0``, ``yes|no``,
-   ``true|false`` into booleans.
-#. ``config.eval`` - safely evaluate strings with Python literals to Python
-   objects (alias to Python's ``ast.literal_eval``).
-#. ``config.list`` - converts comma separated strings into lists.
-#. ``config.tuple`` - converts comma separated strings into tuples.
-#. ``config.option`` - get a return value based on specific options:
-
-.. code-block:: python
-
-    environments = {
-        "production": ("spam", "eggs"),
-        "local": ("spam", "eggs", "test"),
-    }
-
-    # Will return a tuple with ("spam", "eggs") when
-    # ENVIRONMENT is undefined or defined with `production`
-    # and a tuple with ("spam", "eggs", "test") when
-    # ENVIRONMENT is set with `local`.
-    MODULES = config("ENVIRONMENT",
-                     default="production",
-                     cast=Option(environment))
-
-
-Custom casts
-++++++++++++
-
-You can implement your own custom casting function:
-
-.. code-block:: python
-
-   def number_list(value):
-       return [int(v) for v in value.split(";")]
-
-   NUMBERS = config("NUMBERS", default="1;2;3", cast=number_list)
-
-
-Useful third-parties casts
-++++++++++++++++++++++++++
-
-* `dj-database-url`_ - Parses URLs like ``mysql://user:pass@server/db`` into
-  Django ``DATABASES`` configuration format.
-* `django-cache-url`_ - Parses URLs like ``memcached://server:port/prefix``
-  into Django ``CACHES`` configuration format.
-* `dj-email-url`_ - Parses URLs like
-  ``smtp://[email protected]:[email protected]:465/?ssl=True`` with
-  parameters used in Django ``EMAIL_*`` configurations.
-
-
-
-.. _dj-database-url: https://github.com/kennethreitz/dj-database-url
-.. _django-cache-url: https://github.com/ghickman/django-cache-url
-.. _dj-email-url: https://github.com/migonzalvar/dj-email-url