Improve FileAwareEnv docs and add a docstring to the class

docs/tips.rst

@@ -6,19 +6,37 @@ Tips
 Docker-style file based variables
 =================================
 
-To enable Docker-style file based variables (appended with ``_FILE``), use
-``environ.FileAwareEnv`` rather than ``environ.Env``:
+Docker (swarm) and Kubernetes are two widely used platforms that store their
+secrets in tmpfs inside containers as individual files, providing a secure way
+to be able to share configuration data between containers.
+
+Use ``environ.FileAwareEnv`` rather than ``environ.Env`` to first look for
+environment variables with ``_FILE`` appended. If found, their contents will be
+read from the file system and used instead.
+
+For example, given an app with the following in its settings module:
 
 .. code-block:: python
 
-    import environ
+   import environ
+
+   env = environ.FileAwareEnv()
+   SECRET_KEY = env("SECRET_KEY")
+
+the example ``docker-compose.yml`` for would contain:
+
+.. code-block:: yaml
 
-    env = environ.FileAwareEnv()
+   secrets:
+      secret_key:
+      external: true
 
-    # If a ``SECRET_KEY_FILE`` environment variable exists, its contents will be
-    # read from the file system and used instead of the ``SECRET_KEY``
-    # environment variable.
-    SECRET_KEY = env('SECRET_KEY')
+   services:
+      app:
+      secrets:
+         - secret_key
+      environment:
+         - SECRET_KEY_FILE=/run/secrets/secret_key
 
 
 Using unsafe characters in URLs

environ/environ.py

@@ -788,6 +788,20 @@ def read_env(cls, env_file=None, **overrides):
 
 
 class FileAwareEnv(Env):
+    """
+    First look for environment variables with ``_FILE`` appended. If found,
+    their contents will be read from the file system and used instead.
+
+    Use as a drop-in replacement for the standard ``environ.Env``:
+
+    .. code-block:: python
+
+        python env = environ.FileAwareEnv()
+
+    For example, if a ``SECRET_KEY_FILE`` environment variable was set,
+    ``env("SECRET_KEY")`` would find the related variable, returning the file
+    contents rather than ever looking up a ``SECRET_KEY`` environment variable.
+    """
     ENVIRON = FileAwareMapping()