Add api docs

.github/workflows/ci.yml

@@ -93,6 +93,15 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - uses: jupyterlab/maintainer-tools/.github/actions/base-setup@v1
+      - name: Build API docs
+        run: |
+          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
 
   test_without_debugpy:

docs/api/ipykernel.comm.rst

@@ -0,0 +1,25 @@
+ipykernel.comm package
+======================
+
+Submodules
+----------
+
+
+.. automodule:: ipykernel.comm.comm
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.comm.manager
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ipykernel.comm
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/ipykernel.inprocess.rst

@@ -0,0 +1,55 @@
+ipykernel.inprocess package
+===========================
+
+Submodules
+----------
+
+
+.. automodule:: ipykernel.inprocess.blocking
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.inprocess.channels
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.inprocess.client
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.inprocess.constants
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.inprocess.ipkernel
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.inprocess.manager
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.inprocess.socket
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ipykernel.inprocess
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/ipykernel.rst

@@ -0,0 +1,130 @@
+ipykernel package
+=================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   ipykernel.comm
+   ipykernel.inprocess
+
+Submodules
+----------
+
+
+.. automodule:: ipykernel.compiler
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.connect
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.control
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.debugger
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.displayhook
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.embed
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.eventloops
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.heartbeat
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.iostream
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.ipkernel
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.jsonutil
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.kernelapp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.kernelbase
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.kernelspec
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.log
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.parentpoller
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.trio_runner
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: ipykernel.zmqshell
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ipykernel
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/modules.rst

@@ -0,0 +1,7 @@
+ipykernel
+=========
+
+.. toctree::
+   :maxdepth: 4
+
+   ipykernel

docs/conf.py

@@ -34,6 +34,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinxcontrib_github_alt",
+    "sphinx_autodoc_typehints",
 ]
 
 try:

docs/index.rst

@@ -9,9 +9,10 @@ Most IPython kernel documentation is in the `IPython documentation <https://ipyt
 Contents:
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     changelog
+    API docs <api/modules>
 
 
 Indices and tables

ipykernel/comm/comm.py

@@ -18,7 +18,7 @@
 class BaseComm(comm.base_comm.BaseComm):
     """The base class for comms."""
 
-    kernel: Optional[Kernel] = None
+    kernel: Optional["Kernel"] = None
 
     def publish_msg(self, msg_type, data=None, metadata=None, buffers=None, **keys):
         """Helper for sending a comm message on IOPub"""

ipykernel/embed.py

@@ -24,7 +24,7 @@ def embed_kernel(module=None, local_ns=None, **kwargs):
         The module to load into IPython globals (default: caller)
     local_ns : dict, optional
         The namespace to load into IPython user namespace (default: caller)
-    **kwargs : various, optional
+    kwargs : dict, optional
         Further keyword args are relayed to the IPKernelApp constructor,
         allowing configuration of the Kernel.  Will only have an effect
         on the first embed_kernel call for a given process.

pyproject.toml

@@ -45,7 +45,9 @@ docs = [
   "myst_parser",
   "pydata_sphinx_theme",
   "sphinxcontrib_github_alt",
-  "sphinxcontrib-spelling"
+  "sphinxcontrib-spelling",
+  "sphinx-autodoc-typehints",
+  "trio"
 ]
 test = [
     "pytest>=7.0",
@@ -82,6 +84,7 @@ path = "ipykernel/_version.py"
 features = ["docs"]
 [tool.hatch.envs.docs.scripts]
 build = "make -C docs html SPHINXOPTS='-W'"
+api = "sphinx-apidoc -o docs/api -f -E ipykernel ipykernel/tests ipykernel/inprocess/tests ipykernel/datapub.py ipykernel/pickleutil.py ipykernel/serialize.py ipykernel/gui ipykernel/pylab"
 
 [tool.hatch.envs.test]
 features = ["test"]