From 074d173ea72d450544210f83061b9ac50fbdc746 Mon Sep 17 00:00:00 2001
From: cwandrews <cwandrews.oh@gmail.com>
Date: Sun, 1 Oct 2017 21:26:10 -0400
Subject: [PATCH] Added envrionmental_variables page to the guides section.

---
 docs/guide/environmental_variables.rst | 71 ++++++++++++++++++++++++++
 docs/guide/index.rst                   |  1 +
 2 files changed, 72 insertions(+)
 create mode 100644 docs/guide/environmental_variables.rst

diff --git a/docs/guide/environmental_variables.rst b/docs/guide/environmental_variables.rst
new file mode 100644
index 0000000..aa8bbaf
--- /dev/null
+++ b/docs/guide/environmental_variables.rst
@@ -0,0 +1,71 @@
+Environmental Variables
+=======================
+
+Best practice holds that variables should be passed to graphs via environmental variables.
+Doing this is important for keeping sensitive data out of the code - such as an
+API token or username and password used to access a database. Not only is this
+approach more secure, it also makes graphs more flexible by allowing adjustments
+for a variety of environments and contexts. Importantly, environmental variables
+are also the means by-which arguments can be passed to graphs.
+
+
+Passing / Setting Environmental Variables
+::::::::::::::::::::::::::::::::::::::::::::
+
+The recommended way to set environmental variables for a given graph is simply to use
+the optional ``--env`` argument when running bonobo from the shell (bash, command prompt, etc).
+``--env`` (or ``-e`` for short) should then be followed by the variable name and value using the
+syntax `VAR_NAME=VAR_VALUE`. Multiple environmental variables can be passed by using
+multiple ``--env`` / ``-e`` flags.
+
+Example:
+
+.. code-block:: bash
+
+    # Using one environmental variable:
+    bonobo run csvsanitizer --env SECRET_TOKEN=secret123
+
+    # Using multiple environmental variables:
+    bonobo run csvsanitizer -e SRC_FILE=inventory.txt -e DST_FILE=inventory_processed.csv
+
+If you're naming something which is configurable, that is will need to be instantiated or called to obtain something that
+can be used as a graph node, then use camelcase names:
+
+
+Accessing Environmental Variables from within the Graph Context
+:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
+Environmental variables, whether global or only for the scope of the graph,
+can be can be accessed using any of the normal means. It is important to note
+that whether set globally for the system or just for the graph context,
+environmental variables are accessed by bonobo in the same way. In the example
+below the database user and password are accessed via the ``os`` module's ``getenv``
+function and used to get data from the database.
+
+.. code-block:: python
+
+    import os
+
+    from bonobo import Graph, run
+
+
+    def extract():
+        database_user = os.getenv('DB_USER')
+        database_password = os.getenv('DB_PASS')
+        # ...
+        # (connect to database using database_user and database_password)
+        # (get data from database)
+        # ...
+
+        return database_data
+
+
+    def load(database_data: dict):
+        for k, v in database_data.items():
+            print('{key} = {value}'.format(key=k, value=v))
+
+
+    graph = Graph(extract, load)
+
+    if __name__ == '__main__':
+        run(graph)
diff --git a/docs/guide/index.rst b/docs/guide/index.rst
index 18e5565..a05dbf0 100644
--- a/docs/guide/index.rst
+++ b/docs/guide/index.rst
@@ -12,6 +12,7 @@ There are a few things that you should know while writing transformations graphs
     purity
     transformations
     services
+    envrionmental_variables
 
 Third party integrations
 ::::::::::::::::::::::::