From 9e43aba8ee73ff45faca59d640d323b44eb4909d 2023-03-25 20:41:42 From: Philippe Blain Date: 2023-03-25 20:41:42 Subject: [PATCH] docs: add more pointers to configuration of embedded IPython The "Running IPython from Python" section of the docs under "Configuring IPython" gives a nice example of how to set IPython configuration options when embedding IPython. Add more pointer to this part of the documentation by linking to it from the docstrings of IPython.{embed_kernel, start_ipython, start_kernel} and IPython.terminal.embed.embed. While at it, consistenly refer to the config argument as "a traitlets :class:`Config` object". Finally, also mention that options can be set with a 'Config' object in the small paragraph under "IPython options". --- diff --git a/IPython/__init__.py b/IPython/__init__.py index 806566f..4ba3f03 100644 --- a/IPython/__init__.py +++ b/IPython/__init__.py @@ -82,6 +82,7 @@ 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, + such as `config`, a traitlets :class:`Config` object (see :ref:`configure_start_ipython`), allowing configuration of the Kernel. Will only have an effect on the first embed_kernel call for a given process. """ @@ -118,7 +119,7 @@ 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`). """ from IPython.terminal.ipapp import launch_new_instance return launch_new_instance(argv=argv, **kwargs) @@ -143,7 +144,7 @@ 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`). """ import warnings diff --git a/IPython/terminal/embed.py b/IPython/terminal/embed.py index 85e76d5..b5c56b5 100644 --- a/IPython/terminal/embed.py +++ b/IPython/terminal/embed.py @@ -369,8 +369,8 @@ 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. + Full customization can be done by passing a traitlets :class:`Config` in as the + `config` argument (see :ref:`configure_start_ipython`). """ config = kwargs.get('config') if config is None: diff --git a/docs/source/config/intro.rst b/docs/source/config/intro.rst index fa46ba0..8d35660 100644 --- a/docs/source/config/intro.rst +++ b/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 diff --git a/docs/source/config/options/index.rst b/docs/source/config/options/index.rst index a0f38e2..e8fb9b2 100644 --- a/docs/source/config/options/index.rst +++ b/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::