Merge pull request #3812 from minrk/start_ip

Describe differences between start_ipython and embed

in what's new and the embedding section

closes  #3726

docs/source/interactive/reference.rst

@@ -784,17 +784,27 command-line options, as those are trapped first by Python itself.
 Embedding IPython
 =================
 
-It is possible to start an IPython instance inside your own Python
-programs. This allows you to evaluate dynamically the state of your
-code, operate with your variables, analyze them, etc. Note however that
+You can start a regular IPython session with
+
+.. sourcecode:: python
+
+    import IPython
+    IPython.start_ipython()
+
+at any point in your program.  This will load IPython configuration,
+startup files, and everything, just as if it were a normal IPython session.
+In addition to this,
+it is possible to embed an IPython instance inside your own Python programs.
+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.
 
 .. note::
 
-  At present, trying to embed IPython from inside IPython causes problems. Run
-  the code samples below outside IPython.
+  At present, embedding IPython cannot be done from inside IPython.
+  Run the code samples below outside IPython.
 
 This feature allows you to easily have a fully functional python
 environment for doing object introspection anywhere in your code with a

docs/source/whatsnew/version1.0.rst

@@ -63,6 +63,9 there is an official public API for starting IPython:
 
 This is what packages should use that start their own IPython session,
 but don't actually want embedded IPython (most cases).
+:func:`IPython.embed()` is used for embedding IPython into the calling namespace,
+similar to calling :func:`Pdb.set_trace`, whereas :func:`start_ipython`
+will start a plain IPython session, loading config and startup files as normal.
 
 We also have added: