From eded331c9f292a1838602414b6c05928917d13e8 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Sat, 14 Jan 2023 16:45:29 -0600 Subject: [PATCH] Add full api docs (#908) * add full api docs * fix wraps --- .github/workflows/main.yml | 13 +- docs/api/client.rst | 53 -------- docs/api/index.rst | 13 -- docs/api/jupyter_client.asynchronous.rst | 19 +++ docs/api/jupyter_client.blocking.rst | 19 +++ docs/api/jupyter_client.ioloop.rst | 25 ++++ docs/api/jupyter_client.provisioning.rst | 31 +++++ docs/api/jupyter_client.rst | 157 +++++++++++++++++++++++ docs/api/jupyter_client.ssh.rst | 25 ++++ docs/api/kernelspec.rst | 66 ---------- docs/api/manager.rst | 56 -------- docs/api/modules.rst | 7 + docs/api/provisioners.rst | 71 ---------- docs/conf.py | 1 + docs/index.rst | 2 +- jupyter_client/multikernelmanager.py | 2 + jupyter_client/provisioning/factory.py | 6 +- pyproject.toml | 2 + 18 files changed, 301 insertions(+), 267 deletions(-) delete mode 100644 docs/api/client.rst delete mode 100644 docs/api/index.rst create mode 100644 docs/api/jupyter_client.asynchronous.rst create mode 100644 docs/api/jupyter_client.blocking.rst create mode 100644 docs/api/jupyter_client.ioloop.rst create mode 100644 docs/api/jupyter_client.provisioning.rst create mode 100644 docs/api/jupyter_client.rst create mode 100644 docs/api/jupyter_client.ssh.rst delete mode 100644 docs/api/kernelspec.rst delete mode 100644 docs/api/manager.rst create mode 100644 docs/api/modules.rst delete mode 100644 docs/api/provisioners.rst diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index dda73dfa7..cc128bf57 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -71,14 +71,19 @@ jobs: codecov docs: - runs-on: ubuntu-latest + runs-on: windows-latest steps: - uses: actions/checkout@v3 - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1 - - name: Install Dependencies + - name: Build API docs run: | - sudo apt-get update - sudo apt-get install enchant-2 # for spell checking + hatch run docs:api + # If this fails run `hatch run docs:api` locally + # and commit. + git status --porcelain + git status -s | grep "A" && exit 1 + git status -s | grep "M" && exit 1 + echo "API docs done" - run: hatch run docs:build lint: diff --git a/docs/api/client.rst b/docs/api/client.rst deleted file mode 100644 index 9c72e126b..000000000 --- a/docs/api/client.rst +++ /dev/null @@ -1,53 +0,0 @@ -client - communicating with kernels -=================================== - -.. currentmodule:: jupyter_client - -.. seealso:: - - :doc:`/messaging` - The Jupyter messaging specification - -.. autoclass:: KernelClient - - .. automethod:: load_connection_file - - .. automethod:: load_connection_info - - .. automethod:: start_channels - - .. automethod:: execute - - .. automethod:: complete - - .. automethod:: inspect - - .. automethod:: history - - .. automethod:: comm_info - - .. automethod:: is_complete - - .. automethod:: input - - .. automethod:: shutdown - -.. autoclass:: BlockingKernelClient - - .. automethod:: execute_interactive - - .. automethod:: get_shell_msg - - .. automethod:: get_iopub_msg - - .. automethod:: get_stdin_msg - - .. automethod:: get_control_msg - - .. automethod:: wait_for_ready - - .. automethod:: is_alive - -.. autoclass:: AsyncKernelClient - - :class:`AsyncKernelClient` is identical to :class:`BlockingKernelClient` but the methods described above are async. diff --git a/docs/api/index.rst b/docs/api/index.rst deleted file mode 100644 index aace26093..000000000 --- a/docs/api/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -jupyter_client API -================== - -.. module:: jupyter_client - -.. toctree:: - :maxdepth: 2 - :caption: Jupyter API - - kernelspec - manager - client - provisioners diff --git a/docs/api/jupyter_client.asynchronous.rst b/docs/api/jupyter_client.asynchronous.rst new file mode 100644 index 000000000..5fee3b81a --- /dev/null +++ b/docs/api/jupyter_client.asynchronous.rst @@ -0,0 +1,19 @@ +jupyter\_client.asynchronous package +==================================== + +Submodules +---------- + + +.. automodule:: jupyter_client.asynchronous.client + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_client.asynchronous + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/jupyter_client.blocking.rst b/docs/api/jupyter_client.blocking.rst new file mode 100644 index 000000000..ba194cbfe --- /dev/null +++ b/docs/api/jupyter_client.blocking.rst @@ -0,0 +1,19 @@ +jupyter\_client.blocking package +================================ + +Submodules +---------- + + +.. automodule:: jupyter_client.blocking.client + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_client.blocking + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/jupyter_client.ioloop.rst b/docs/api/jupyter_client.ioloop.rst new file mode 100644 index 000000000..2c06a8322 --- /dev/null +++ b/docs/api/jupyter_client.ioloop.rst @@ -0,0 +1,25 @@ +jupyter\_client.ioloop package +============================== + +Submodules +---------- + + +.. automodule:: jupyter_client.ioloop.manager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.ioloop.restarter + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_client.ioloop + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/jupyter_client.provisioning.rst b/docs/api/jupyter_client.provisioning.rst new file mode 100644 index 000000000..5a2de00f9 --- /dev/null +++ b/docs/api/jupyter_client.provisioning.rst @@ -0,0 +1,31 @@ +jupyter\_client.provisioning package +==================================== + +Submodules +---------- + + +.. automodule:: jupyter_client.provisioning.factory + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.provisioning.local_provisioner + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.provisioning.provisioner_base + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_client.provisioning + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/jupyter_client.rst b/docs/api/jupyter_client.rst new file mode 100644 index 000000000..336dcc2d1 --- /dev/null +++ b/docs/api/jupyter_client.rst @@ -0,0 +1,157 @@ +jupyter\_client package +======================= + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + jupyter_client.asynchronous + jupyter_client.blocking + jupyter_client.ioloop + jupyter_client.provisioning + jupyter_client.ssh + +Submodules +---------- + + +.. automodule:: jupyter_client.adapter + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.channels + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.channelsabc + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.client + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.clientabc + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.connect + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.consoleapp + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.jsonutil + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.kernelapp + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.kernelspec + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.kernelspecapp + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.launcher + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.localinterfaces + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.manager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.managerabc + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.multikernelmanager + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.restarter + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.runapp + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.session + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.threaded + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.utils + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.win_interrupt + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_client + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/jupyter_client.ssh.rst b/docs/api/jupyter_client.ssh.rst new file mode 100644 index 000000000..06a1d9db6 --- /dev/null +++ b/docs/api/jupyter_client.ssh.rst @@ -0,0 +1,25 @@ +jupyter\_client.ssh package +=========================== + +Submodules +---------- + + +.. automodule:: jupyter_client.ssh.forward + :members: + :undoc-members: + :show-inheritance: + + +.. automodule:: jupyter_client.ssh.tunnel + :members: + :undoc-members: + :show-inheritance: + +Module contents +--------------- + +.. automodule:: jupyter_client.ssh + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/api/kernelspec.rst b/docs/api/kernelspec.rst deleted file mode 100644 index 6bccc086d..000000000 --- a/docs/api/kernelspec.rst +++ /dev/null @@ -1,66 +0,0 @@ -kernelspec - discovering kernels -================================ - -.. seealso:: :ref:`kernelspecs` - -.. module:: jupyter_client.kernelspec - -.. class:: KernelSpec - - .. attribute:: argv - - The list of arguments to start this kernel. - - .. attribute:: env - - A dictionary of extra environment variables to declare, in addition to - the current environment variables, when launching this kernel. - - .. attribute:: display_name - - The name to display for this kernel in UI. - - .. attribute:: language - - The name of the language the kernel implements, to help with picking - appropriate kernels when loading notebooks. - - .. attribute:: metadata - - Additional kernel-specific metadata; clients can use this as needed, - for instance to aid in kernel selection and filtering. - - Metadata added here should be namespaced for the tool reading and - writing that metadata. Concretely, if you're adding a new field called - :code:`supported_versions` which your tool recognizes, then you should - add it as :code:`"mytool": {"supported_versions": [1, 2]}`, **not** as a - top-level field called :code:`supported_versions`. - - .. attribute:: resource_dir - - The path to the directory with this kernel's resources, such as icons. - - .. automethod:: to_json - -.. class:: KernelSpecManager - - .. automethod:: find_kernel_specs - - .. automethod:: get_all_specs - - .. automethod:: get_kernel_spec - - .. automethod:: install_kernel_spec - -.. exception:: NoSuchKernel - - .. attribute:: name - - The name of the kernel which was requested. - -.. function:: find_kernel_specs - get_kernel_spec(kernel_name) - install_kernel_spec(source_dir, kernel_name=None, user=False, replace=False) - - These methods from :class:`KernelSpecManager` are exposed as functions on the - module as well; they will use all the default settings. diff --git a/docs/api/manager.rst b/docs/api/manager.rst deleted file mode 100644 index 66194fddb..000000000 --- a/docs/api/manager.rst +++ /dev/null @@ -1,56 +0,0 @@ -manager - starting, stopping, signalling -======================================== - -.. currentmodule:: jupyter_client - -.. autoclass:: KernelManager - - .. attribute:: kernel_name - - The name of the kernel to launch (see :ref:`kernelspecs`). - - .. autoattribute:: provisioner - - The kernel provisioner with which this :class:`KernelManager` is communicating. This will generally be a :class:`LocalProvisioner` instance unless the kernelspec indicates otherwise. - - .. automethod:: start_kernel - - .. automethod:: is_alive - - .. automethod:: interrupt_kernel - - .. automethod:: signal_kernel - - .. automethod:: client - - For the client API, see :mod:`jupyter_client.client`. - - .. automethod:: blocking_client - - .. automethod:: shutdown_kernel - - .. automethod:: restart_kernel - -multikernelmanager - controlling multiple kernels -------------------------------------------------- - -.. autoclass:: MultiKernelManager - - This exposes the same methods as :class:`~jupyter_client.manager.KernelManager`, - but their first parameter is a kernel ID, a string identifying the kernel - instance. Typically these are UUIDs picked by :meth:`start_kernel` - - .. automethod:: start_kernel - - .. automethod:: list_kernel_ids - - .. automethod:: get_kernel - - .. automethod:: remove_kernel - - .. automethod:: shutdown_all - -Utility functions ------------------ - -.. autofunction:: run_kernel diff --git a/docs/api/modules.rst b/docs/api/modules.rst new file mode 100644 index 000000000..1cb39d0fb --- /dev/null +++ b/docs/api/modules.rst @@ -0,0 +1,7 @@ +jupyter_client +============== + +.. toctree:: + :maxdepth: 4 + + jupyter_client diff --git a/docs/api/provisioners.rst b/docs/api/provisioners.rst deleted file mode 100644 index d468960e9..000000000 --- a/docs/api/provisioners.rst +++ /dev/null @@ -1,71 +0,0 @@ -kernel provisioner apis -======================= - -.. seealso:: - - :doc:`/provisioning` - -.. module:: jupyter_client.provisioning.provisioner_base - -.. autoclass:: KernelProvisionerBase - - .. attribute:: kernel_spec - - The kernel specification associated with the provisioned kernel (see :ref:`kernelspecs`). - - .. attribute:: kernel_id - - The provisioned kernel's ID. - - .. attribute:: connection_info - - The provisioned kernel's connection information. - - - .. autoproperty:: has_process - - .. automethod:: poll - - .. automethod:: wait - - .. automethod:: send_signal - - .. automethod:: kill - - .. automethod:: terminate - - .. automethod:: launch_kernel - - .. automethod:: cleanup - - .. automethod:: shutdown_requested - - .. automethod:: pre_launch - - .. automethod:: post_launch - - .. automethod:: get_provisioner_info - - .. automethod:: load_provisioner_info - - .. automethod:: get_shutdown_wait_time - - .. automethod:: _finalize_env - - .. automethod:: __apply_env_substitutions - -.. module:: jupyter_client.provisioning.local_provisioner - -.. autoclass:: LocalProvisioner - -.. module:: jupyter_client.provisioning.factory - -.. autoclass:: KernelProvisionerFactory - - .. attribute:: default_provisioner_name - - Indicates the name of the provisioner to use when no kernel_provisioner entry is present in the kernel specification. This value can also be specified via the environment variable ``JUPYTER_DEFAULT_PROVISIONER_NAME``. - - .. automethod:: is_provisioner_available - - .. automethod:: create_provisioner_instance diff --git a/docs/conf.py b/docs/conf.py index b1119f561..2b6d823e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,6 +34,7 @@ 'sphinx.ext.intersphinx', 'sphinx.ext.napoleon', 'sphinxcontrib_github_alt', + "sphinx_autodoc_typehints", ] try: diff --git a/docs/index.rst b/docs/index.rst index 4731a328d..f2cc206be 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,7 +30,7 @@ with Jupyter kernels. :maxdepth: 2 :caption: API - api/index + API Docs .. toctree:: :maxdepth: 2 diff --git a/jupyter_client/multikernelmanager.py b/jupyter_client/multikernelmanager.py index 5cf11b5f9..dab9a80c5 100644 --- a/jupyter_client/multikernelmanager.py +++ b/jupyter_client/multikernelmanager.py @@ -6,6 +6,7 @@ import socket import typing as t import uuid +from functools import wraps import zmq from traitlets import Any, Bool, Dict, DottedObjectName, Instance, Unicode, default, observe @@ -24,6 +25,7 @@ class DuplicateKernelError(Exception): def kernel_method(f: t.Callable) -> t.Callable: """decorator for proxying MKM.method(kernel_id) to individual KMs by ID""" + @wraps(f) def wrapped( self: t.Any, kernel_id: str, *args: t.Any, **kwargs: t.Any ) -> t.Union[t.Callable, t.Awaitable]: diff --git a/jupyter_client/provisioning/factory.py b/jupyter_client/provisioning/factory.py index cc2bcb4cb..4e1c7aaa6 100644 --- a/jupyter_client/provisioning/factory.py +++ b/jupyter_client/provisioning/factory.py @@ -26,7 +26,7 @@ class KernelProvisionerFactory(SingletonConfigurable): availability (in cases where the kernel specification references a kernel provisioner that has not been installed into the current Python environment). - It's `default_provisioner_name` attribute can be used to specify the default provisioner + It's ``default_provisioner_name`` attribute can be used to specify the default provisioner to use when a kernel_spec is found to not reference a provisioner. It's value defaults to `"local-provisioner"` which identifies the local provisioner implemented by :class:`LocalProvisioner`. @@ -43,7 +43,7 @@ class KernelProvisionerFactory(SingletonConfigurable): ) @default('default_provisioner_name') - def default_provisioner_name_default(self): + def _default_provisioner_name_default(self): """The default provisioner name.""" return getenv(self.default_provisioner_name_env, "local-provisioner") @@ -80,7 +80,7 @@ def create_provisioner_instance( Reads the associated ``kernel_spec`` to see if it has a `kernel_provisioner` stanza. If one exists, it instantiates an instance. If a kernel provisioner is not specified in the kernel specification, a default provisioner stanza is fabricated - and instantiated corresponding to the current value of `default_provisioner_name` trait. + and instantiated corresponding to the current value of ``default_provisioner_name`` trait. The instantiated instance is returned. If the provisioner is found to not exist (not registered via entry_points), diff --git a/pyproject.toml b/pyproject.toml index d875e8a5e..e2674f26a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -66,6 +66,7 @@ docs = [ "pydata_sphinx_theme", "sphinxcontrib_github_alt", "sphinxcontrib-spelling", + "sphinx-autodoc-typehints", ] [project.scripts] @@ -84,6 +85,7 @@ validate-bump = false features = ["docs"] [tool.hatch.envs.docs.scripts] build = "make -C docs html SPHINXOPTS='-W'" +api = "sphinx-apidoc -o docs/api -f -E jupyter_client" [tool.hatch.envs.test] features = ["test"]