Add api docs (#328)

Author: blink1073

.github/workflows/test.yml

@@ -83,6 +83,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_lint:

docs/api/jupyter_core.rst

@@ -0,0 +1,57 @@
+jupyter\_core package
+=====================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   jupyter_core.utils
+
+Submodules
+----------
+
+
+.. automodule:: jupyter_core.application
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: jupyter_core.command
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: jupyter_core.migrate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: jupyter_core.paths
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: jupyter_core.troubleshoot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. automodule:: jupyter_core.version
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: jupyter_core
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/jupyter_core.utils.rst

@@ -0,0 +1,10 @@
+jupyter\_core.utils package
+===========================
+
+Module contents
+---------------
+
+.. automodule:: jupyter_core.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/modules.rst

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

docs/conf.py

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

docs/index.rst

@@ -10,9 +10,8 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
-   paths
    changelog
-
+   API Docs <api/modules>
 
 Indices and tables
 ==================

docs/paths.rst

@@ -7,11 +7,14 @@
 - .ipython/
   - nbextensions -> JUPYTER_DATA_DIR/nbextensions
   - kernels ->  JUPYTER_DATA_DIR/kernels
+
 - .ipython/profile_default/
   - static/custom -> .jupyter/custom
   - nbconfig -> .jupyter/nbconfig
   - security/
+
     - notebook_secret, notebook_cookie_secret, nbsignatures.db -> JUPYTER_DATA_DIR
+
   - ipython_{notebook,nbconvert,qtconsole}_config.py -> .jupyter/jupyter_{name}_config.py
 
 
@@ -183,7 +186,7 @@ def migrate_static_custom(src, dst):
 
 
 def migrate_config(name, env):
-    """Migrate a config file
+    """Migrate a config file.
 
     Includes substitutions for updated configurable names.
     """

jupyter_core/migrate.py

@@ -14,7 +14,8 @@
 
 
 def ensure_dir_exists(path, mode=0o777):
-    """ensure that a directory exists
+    """Ensure that a directory exists
+
     If it doesn't exist, try to create it, protecting against a race condition
     if another process is doing the same.
     The default permissions are determined by the current umask.
@@ -134,6 +135,7 @@ def run_sync(coro: Callable[..., Awaitable[T]]) -> Callable[..., T]:
     ----------
     coro : coroutine
         The coroutine to be executed.
+
     Returns
     -------
     result :

jupyter_core/utils/__init__.py

@@ -50,6 +50,7 @@ docs = [
   "myst-parser",
   "sphinxcontrib_github_alt",
   "sphinxcontrib_spelling",
+  "sphinx-autodoc-typehints",
   "traitlets",
 ]
 
@@ -66,8 +67,11 @@ path = "jupyter_core/version.py"
 
 [tool.hatch.envs.docs]
 features = ["docs"]
+[tool.hatch.envs.docs.env-vars]
+SPHINXOPTS = "-W -n"
 [tool.hatch.envs.docs.scripts]
-build = "make -C docs html SPHINXOPTS='-W'"
+build = "make -C docs html"
+api = "sphinx-apidoc -o docs/api -f -E jupyter_core jupyter_core/tests/*"
 
 [tool.hatch.envs.test]
 features = ["test"]