Merge pull request #10891 from lesley2958/master

document change for ipython embedding global namespace

docs/source/interactive/reference.rst

@@ -607,12 +607,66 b' startup files, and everything, just as if it were a normal IPython session.'
 For information on setting configuration options when running IPython from
 python, see :ref:`configure_start_ipython`.
 
-It is also possible to embed an IPython shell in a namespace in your Python code.
-This allows you to evaluate dynamically the state of your code,
-operate with your variables, analyze them, etc. Note however that
-any changes you make to values while in the shell do not propagate back
-to the running code, so it is safe to modify your values because you
-won't break your code in bizarre ways by doing so.
+It is also possible to embed an IPython shell in a namespace in your Python
+code. This allows you to evaluate dynamically the state of your code, operate
+with your variables, analyze them, etc. For example, if you run the following
+code snippet::
+
+  import IPython
+
+  a = 42
+  IPython.embed()
+
+and within the IPython shell, you reassign `a` to `23` to do further testing of 
+some sort, you can then exit::
+
+  >>> IPython.embed()
+  Python 3.6.2 (default, Jul 17 2017, 16:44:45) 
+  Type 'copyright', 'credits' or 'license' for more information
+  IPython 6.2.0.dev -- An enhanced Interactive Python. Type '?' for help.
+
+  In [1]: a = 23
+
+  In [2]: exit()
+
+Once you exit and print `a`, the value 23 will be shown::
+
+
+  In: print(a)
+  23
+
+It's important to note that the code run in the embedded IPython shell will 
+*not* change the state of your code and variables, **unless** the shell is 
+contained within the global namespace. In the above example, `a` is changed 
+because this is true.
+
+To further exemplify this, consider the following example::
+
+  import IPython
+  def do():
+      a = 42
+      print(a)
+      IPython.embed()
+      print(a)
+
+Now if call the function and complete the state changes as we did above, the
+value `42` will be printed. Again, this is because it's not in the global
+namespace:: 
+
+  do()
+
+Running a file with the above code can lead to the following session::
+
+  >>> do()
+  42
+  Python 3.6.2 (default, Jul 17 2017, 16:44:45) 
+  Type 'copyright', 'credits' or 'license' for more information
+  IPython 6.2.0.dev -- An enhanced Interactive Python. Type '?' for help.
+
+  In [1]: a = 23
+
+  In [2]: exit()
+  42
 
 .. note::