Improve API documentation around configuration of embedded IPython (#…

…13989)

This PR tries to improve the API documentation of `embed()`,
`embed_kernel()`, `start_ipython()` and `start_kernel()` with respect to
the configuration of IPython by adding links to other sections of the
documentation. It also reorganizes the API docs so that `embed()` is
listed under `IPython`, just as it's presented in the narrative
documentation.

.gitignore

@@ -6,6 +6,7 @@ docs/man/*.gz
 docs/source/api/generated
 docs/source/config/options
 docs/source/config/shortcuts/*.csv
+docs/source/config/shortcuts/table.tsv
 docs/source/savefig
 docs/source/interactive/magics-generated.txt
 docs/gh-pages

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
@@ -82,7 +84,8 @@ def embed_kernel(module=None, local_ns=None, **kwargs):
         The namespace to load into IPython user namespace (default: caller)
     **kwargs : various, optional
         Further keyword args are relayed to the IPKernelApp constructor,
-        allowing configuration of the Kernel.  Will only have an effect
+        such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
+        allowing configuration of the kernel (see :ref:`kernel_options`).  Will only have an effect
         on the first embed_kernel call for a given process.
     """
 
@@ -118,7 +121,8 @@ def start_ipython(argv=None, **kwargs):
         specify this dictionary to initialize the IPython user namespace with particular values.
     **kwargs : various, optional
         Any other kwargs will be passed to the Application constructor,
-        such as `config`.
+        such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
+        allowing configuration of the instance (see :ref:`terminal_options`).
     """
     from IPython.terminal.ipapp import launch_new_instance
     return launch_new_instance(argv=argv, **kwargs)
@@ -132,7 +136,7 @@ def start_kernel(argv=None, **kwargs):
 
     `start_kernel()` does full, regular IPython initialization,
     including loading startup files, configuration, etc.
-    much of which is skipped by `embed()`.
+    much of which is skipped by `embed_kernel()`.
 
     Parameters
     ----------
@@ -143,7 +147,8 @@ def start_kernel(argv=None, **kwargs):
         specify this dictionary to initialize the IPython user namespace with particular values.
     **kwargs : various, optional
         Any other kwargs will be passed to the Application constructor,
-        such as `config`.
+        such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
+        allowing configuration of the kernel (see :ref:`kernel_options`).
     """
     import warnings
 

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.
 
@@ -369,8 +369,18 @@ def embed(*, header="", compile_flags=None, **kwargs):
         d = 40
         embed()
 
-    Full customization can be done by passing a :class:`Config` in as the
-    config argument.
+    Parameters
+    ----------
+
+    header : str
+        Optional header string to print at startup.
+    compile_flags
+        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:`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`).
     """
     config = kwargs.get('config')
     if config is None:

docs/README.rst

@@ -26,7 +26,7 @@ the following tools are needed to build the documentation:
 In a conda environment, or a Python 3 ``venv``, you should be able to run::
 
   cd ipython
-  pip install .[doc] -U
+  pip install -U -r docs/requirements.txt
 
 
 Build Commands

docs/autogen_api.py

@@ -66,10 +66,13 @@
     # 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

docs/autogen_config.py

@@ -103,6 +103,7 @@ def write_doc(name, title, app, preamble=None):
     trait_aliases = reverse_aliases(app)
     filename = options / (name + ".rst")
     with open(filename, "w", encoding="utf-8") as f:
+        f.write(".. _" + name + "_options:" + "\n\n")
         f.write(title + "\n")
         f.write(("=" * len(title)) + "\n")
         f.write("\n")

docs/autogen_shortcuts.py

@@ -17,7 +17,7 @@
 @dataclass
 class Shortcut:
     #: a sequence of keys (each element on the list corresponds to pressing one or more keys)
-    keys_sequence: list[str]
+    keys_sequence: List[str]
     filter: str
 
 
@@ -146,7 +146,7 @@ def to_rst(key):
         escaped = key.replace("\\", "\\\\")
         return f":kbd:`{escaped}`"
 
-    keys_to_press: list[str]
+    keys_to_press: List[str]
 
     prefixes = {
         "c-s-": [to_rst("ctrl"), to_rst("shift")],

docs/source/config/intro.rst

@@ -153,7 +153,7 @@ Running IPython from Python
 
 If you are using :ref:`embedding` to start IPython from a normal 
 python file, you can set configuration options the same way as in a 
-config file by creating a traitlets config object and passing it to 
+config file by creating a traitlets :class:`Config` object and passing it to 
 start_ipython like in the example below.
 
 .. literalinclude:: ../../../examples/Embedding/start_ipython_config.py

docs/source/config/options/index.rst

@@ -3,8 +3,8 @@ IPython options
 ===============
 
 Any of the options listed here can be set in config files, at the
-command line, or from inside IPython. See :ref:`setting_config` for
-details.
+command line, from inside IPython, or using a traitlets :class:`Config` object.
+See :ref:`setting_config` for details.
 
 .. toctree::