docs: document embed() under IPython

The narrative documentation refers to embed() as IPython.embed(), but
this function is not documented under the IPython module in the API
docs, it is under IPython.terminal.embed. This is because IPython is not
listed in the __names_from_all__ list in autogen_api.py, so only
functions defined directly in IPython/__init__.py are listed, and
embed() is _imported_ there from IPython.terminal.embed.

Add the documentation of embed directly under the IPython module by
adding 'IPython' to the __names_from_all__ list. Note that we avoid
excluding IPython.terminal.embed in the lists of patterns to skip since
we still want to document the rest of the names in this module.

Add an explicit __all__ list in IPython/__init__.py, listing the
currently documented functions as well as embed().

Finally, tweak the embed() docstring to refer explicitely to
terminal.embed.InteractiveShellEmbed so that these links keep working.

IPython/__init__.py

@@ -56,6 +56,8 @@
 from .utils.sysinfo import sys_info
 from .utils.frame import extract_module_locals
 
+__all__ = ["start_ipython", "embed", "start_kernel", "embed_kernel"]
+
 # Release data
 __author__ = '%s <%s>' % (release.author, release.author_email)
 __license__  = release.license

IPython/terminal/embed.py

@@ -350,7 +350,7 @@ def mainloop(
 def embed(*, header="", compile_flags=None, **kwargs):
     """Call this to embed IPython at the current point in your program.
 
-    The first invocation of this will create an :class:`InteractiveShellEmbed`
+    The first invocation of this will create a :class:`terminal.embed.InteractiveShellEmbed`
     instance and then call it.  Consecutive calls just call the already
     created instance.
 
@@ -375,10 +375,10 @@ def embed(*, header="", compile_flags=None, **kwargs):
     header : str
         Optional header string to print at startup.
     compile_flags
-        Passed to the `compile_flags` parameter of :py:meth:`InteractiveShellEmbed.mainloop()`,
-        which is called when the :class:`InteractiveShellEmbed` instance is called.
+        Passed to the `compile_flags` parameter of :py:meth:`terminal.embed.InteractiveShellEmbed.mainloop()`,
+        which is called when the :class:`terminal.embed.InteractiveShellEmbed` instance is called.
     **kwargs : various, optional
-        Any other kwargs will be passed to the :class:`InteractiveShellEmbed` constructor.
+        Any other kwargs will be passed to the :class:`terminal.embed.InteractiveShellEmbed` constructor.
         Full customization can be done by passing a traitlets :class:`Config` in as the
         `config` argument (see :ref:`configure_start_ipython` and :ref:`terminal_options`).
     """

docs/autogen_api.py

@@ -67,6 +67,7 @@
     # non-API modules they import from should be excluded by the skip patterns
     # above.
     docwriter.names_from__all__.update({
+        'IPython',
         'IPython.display',
     })