From ad452c1d8bb25e742caa152fb301e0e6626b6faa 2023-03-30 08:26:39 From: Matthias Bussonnier Date: 2023-03-30 08:26:39 Subject: [PATCH] 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. --- diff --git a/.gitignore b/.gitignore index 3b6963b..06087b7 100644 --- a/.gitignore +++ b/.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 diff --git a/IPython/__init__.py b/IPython/__init__.py index 7d3799a..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 @@ -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 diff --git a/IPython/terminal/embed.py b/IPython/terminal/embed.py index 85e76d5..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. @@ -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: diff --git a/docs/README.rst b/docs/README.rst index 4bfc5b1..ebdb171 100644 --- a/docs/README.rst +++ b/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 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 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") diff --git a/docs/autogen_shortcuts.py b/docs/autogen_shortcuts.py index 15bb0ee..387c105 100755 --- a/docs/autogen_shortcuts.py +++ b/docs/autogen_shortcuts.py @@ -17,7 +17,7 @@ from IPython.terminal.shortcuts.filters import KEYBINDING_FILTERS @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 format_prompt_keys(keys: str, add_alternatives=True) -> str: 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")], 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::