From 1d7eee5d2f04a046007cad0ad922df0f007f910f 2023-03-25 20:41:42
From: Philippe Blain <levraiphilippeblain@gmail.com>
Date: 2023-03-25 20:41:42
Subject: [PATCH] docs: add pointers to IPython and kernel options

The docstrings of embed_kernel, start_ipython, start_kernel and embed
mention that a traitlets Config can be passed as 'config' to configure
the app / kernel, but the available options are not mentioned.

Adjust write_doc in 'autogen_config.py' so that it adds a label before
the title of each documented class, and use that label to link to the
IPython terminal options from the docstrings of start_ipython and embed,
and to the kernel options from the docstrings of start_kernel and
embed_kernel.

---

diff --git a/IPython/__init__.py b/IPython/__init__.py
index 4ba3f03..bafd105 100644
--- a/IPython/__init__.py
+++ b/IPython/__init__.py
@@ -83,7 +83,7 @@ def embed_kernel(module=None, local_ns=None, **kwargs):
     **kwargs : various, optional
         Further keyword args are relayed to the IPKernelApp constructor,
         such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
-        allowing configuration of the Kernel.  Will only have an effect
+        allowing configuration of the kernel (see :ref:`kernel_options`).  Will only have an effect
         on the first embed_kernel call for a given process.
     """
     
@@ -119,7 +119,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`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`).
+        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)
@@ -144,7 +145,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`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`).
+        such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`),
+        allowing configuration of the kernel (see :ref:`kernel_options`).
     """
     import warnings
 
diff --git a/IPython/terminal/embed.py b/IPython/terminal/embed.py
index 4eaf952..85f89e0 100644
--- a/IPython/terminal/embed.py
+++ b/IPython/terminal/embed.py
@@ -380,7 +380,7 @@ def embed(*, header="", compile_flags=None, **kwargs):
     **kwargs : various, optional
         Any other kwargs will be passed to the :class:`InteractiveShellEmbed` constructor.
         Full customization can be done by passing a traitlets :class:`Config` in as the
-        `config` argument (see :ref:`configure_start_ipython`).
+        `config` argument (see :ref:`configure_start_ipython` and :ref:`terminal_options`).
     """
     config = kwargs.get('config')
     if config is None:
diff --git a/docs/autogen_config.py b/docs/autogen_config.py
index 43c38dd..5bfa67e 100755
--- a/docs/autogen_config.py
+++ b/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")