From e7d63e081577e33e829fcd0753ba482e2b486a9d Mon Sep 17 00:00:00 2001
From: Peter Bittner <django@bittner.it>
Date: Mon, 10 Dec 2018 03:31:01 +0100
Subject: [PATCH] Explain how to read .env files

---
 docs/cookbook.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/cookbook.rst b/docs/cookbook.rst
index 93b781b..7ab5637 100644
--- a/docs/cookbook.rst
+++ b/docs/cookbook.rst
@@ -20,6 +20,37 @@ Simply import it from ``configurations.management`` instead:
 
     call_command('dumpdata', exclude=['contenttypes', 'auth'])
 
+Read .env file
+--------------
+
+Configurations can read values for environment variables out of an ``.env``
+file, and push them into the application's process environment. Simply set
+the ``DOTENV`` setting to the appropriate file name:
+
+.. code-block:: python
+
+   # mysite/settings.py
+
+   from os.path import dirname, join
+   from configurations import Configuration
+
+   BASE_DIR = dirname(dirname(__file__))
+
+   class Dev(Configuration):
+       DOTENV = join(BASE_PATH, '.env')
+
+       SECRET_KEY = values.SecretValue()
+
+An ``.env`` file is an ``.ini``-style file. It must contain a list of
+``KEY=value`` pairs, just like Shell environment variables:
+
+.. code-block:: ini
+
+   # .env
+
+   DJANGO_DEBUG=False
+   DJANGO_SECRET_KEY=1q2w3e4r5t6z7u8i9o0(%&)$§"!pqaycz
+
 Envdir
 ------