From 853291bb3104475994842f3ea9fda44ee938177d 2023-03-25 20:44:49
From: Philippe Blain <levraiphilippeblain@gmail.com>
Date: 2023-03-25 20:44:49
Subject: [PATCH] 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. Note
also that darker insists on reformatting this list.

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.

---

diff --git a/IPython/__init__.py b/IPython/__init__.py
index bafd105..e930dfc 100644
--- a/IPython/__init__.py
+++ b/IPython/__init__.py
@@ -56,6 +56,8 @@ from .core.interactiveshell import InteractiveShell
 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
diff --git a/IPython/terminal/embed.py b/IPython/terminal/embed.py
index 85f89e0..ce5ee01 100644
--- a/IPython/terminal/embed.py
+++ b/IPython/terminal/embed.py
@@ -350,7 +350,7 @@ class InteractiveShellEmbed(TerminalInteractiveShell):
 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`).
     """
diff --git a/docs/autogen_api.py b/docs/autogen_api.py
index d2fdfae..0011900 100755
--- a/docs/autogen_api.py
+++ b/docs/autogen_api.py
@@ -66,10 +66,13 @@ if __name__ == '__main__':
     # them as part of the public API. They must have __all__ defined. The
     # non-API modules they import from should be excluded by the skip patterns
     # above.
-    docwriter.names_from__all__.update({
-        'IPython.display',
-    })
-    
+    docwriter.names_from__all__.update(
+        {
+            "IPython",
+            "IPython.display",
+        }
+    )
+
     # Now, generate the outputs
     docwriter.write_api_docs(outdir)
     # Write index with .txt extension - we can include it, but Sphinx won't try