From ac0288d3823e091a779823e16a87c8134925c9fb Mon Sep 17 00:00:00 2001
From: Olivier Delalleau <507137+odelalleau@users.noreply.github.com>
Date: Wed, 31 Mar 2021 15:01:46 -0400
Subject: [PATCH] Synch notebook with doc (#655)

Some doc updates from #606 were not fully ported to the notebook.
---
 docs/notebook/Tutorial.ipynb | 19 +++++++++++--------
 1 file changed, 11 insertions(+), 8 deletions(-)

diff --git a/docs/notebook/Tutorial.ipynb b/docs/notebook/Tutorial.ipynb
index 597420f32..b322d4344 100644
--- a/docs/notebook/Tutorial.ipynb
+++ b/docs/notebook/Tutorial.ipynb
@@ -699,8 +699,7 @@
    "source": [
     "## Environment variable interpolation\n",
     "\n",
-    "Environment variable interpolation is also supported.\n",
-    "An environment variable is always returned as a string."
+    "Access to environment variables is supported using ``oc.env``."
    ]
   },
   {
@@ -778,7 +777,7 @@
     "You can specify a default value to use in case the environment variable is not defined.\n",
     "This default value can be a string or ``null`` (representing Python ``None``). Passing a default with a different type will result in an error.\n",
     "\n",
-    "The following example sets default database passwords when ``DB_PASSWORD`` is not defined:"
+    "The following example falls back to default passwords when ``DB_PASSWORD`` is not defined:"
    ]
   },
   {
@@ -820,8 +819,12 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "You can automatically convert a string to its corresponding type (e.g., bool, int, float, dict, list) using `oc.decode` (which can even resolve interpolations).\n",
-    "This resolver also accepts ``None`` as input, in which case it returns ``None``.\n",
+    "Strings may be converted using ``oc.decode``:\n",
+    "\n",
+    "- Primitive values (e.g., ``\"true\"``, ``\"1\"``, ``\"1e-3\"``) are automatically converted to their corresponding type (bool, int, float)\n",
+    "- Dictionaries and lists (e.g., ``\"{a: b}\"``, ``\"[a, b, c]\"``)  are returned as transient config nodes (DictConfig and ListConfig)\n",
+    "- Interpolations (e.g., ``\"${foo}\"``) are automatically resolved\n",
+    "- ``None`` is the only valid non-string input to ``oc.decode`` (returning ``None`` in that case)\n",
     "\n",
     "This can be useful for instance to parse environment variables:"
    ]
@@ -846,9 +849,9 @@
     "cfg = OmegaConf.create(\n",
     "    {\n",
     "        \"database\": {\n",
-    "            \"port\": '${oc.decode:${oc.env:DB_PORT}}',\n",
-    "            \"nodes\": '${oc.decode:${oc.env:DB_NODES,null}}',\n",
-    "            \"timeout\": '${oc.decode:${oc.env:DB_TIMEOUT,null}}',\n",
+    "            \"port\": \"${oc.decode:${oc.env:DB_PORT}}\",\n",
+    "            \"nodes\": \"${oc.decode:${oc.env:DB_NODES}}\",\n",
+    "            \"timeout\": \"${oc.decode:${oc.env:DB_TIMEOUT,null}}\",\n",
     "        }\n",
     "    }\n",
     ")\n",