Clean up docs build and typing (#1168)

Fixes #1125

Author: blink1073

docs/Makefile

@@ -53,15 +53,11 @@ clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf source/config.rst
 
-html: source/config.rst
+html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-source/config.rst:
-	python3 autogen_config.py
-	@echo "Created docs for config options"
-
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

docs/autogen_config.py

@@ -11,56 +11,14 @@
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
-import logging
 import os
 import os.path as osp
 import shutil
 import sys
-from importlib.metadata import version
-
-from packaging.version import parse as parse_version
 
 HERE = osp.abspath(osp.dirname(__file__))
-
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-# DEBUG for RTD
-log = logging.getLogger(__name__)
-info = log.info
-info("DEBUG:: sys.path")
-info("================")
-for item in sys.path:
-    info(item)
-
-# add repo root to sys.path
-# here = root/docs/source
-here = os.path.abspath(os.path.dirname(__file__))
-repo_root = os.path.dirname(os.path.dirname(here))
-sys.path.insert(0, repo_root)
-
-info("repo_root")
-info("=====================")
-info(repo_root)
-
-# DEBUG for post insert on RTD
-info("DEBUG:: Post insert to sys.path")
-info("===============================")
-for item in sys.path:
-    info(item)
-
-# Check if docs are being built by ReadTheDocs
-# If so, generate a config.rst file and populate it with documentation about
-# configuration options
-
-if os.environ.get("READTHEDOCS", ""):
-
-    # Readthedocs doesn't run our Makefile, so we do this to force it to generate
-    # the config docs.
-    with open("../autogen_config.py") as f:
-        exec(compile(f.read(), "../autogen_config.py", "exec"), {})  # noqa
+sys.path.insert(0, osp.join(HERE, "..", ""))
+from jupyter_server._version import version_info
 
 # -- General configuration ------------------------------------------------
 
@@ -119,10 +77,8 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-__version__ = version("jupyter_server")
 # The short X.Y version.
-version_parsed = parse_version(__version__)
-version = f"{version_parsed.major}.{version_parsed.minor}"  # type:ignore
+version = f"{version_info[0]}.{version_info[1]}"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -382,7 +338,48 @@
 # import before any doc is built, so _ is guaranteed to be injected
 import jupyter_server.transutils  # noqa: F401
 
+CONFIG_HEADER = """\
+.. _other-full-config:
+
+
+Config file and command line options
+====================================
+
+The Jupyter Server can be run with a variety of command line arguments.
+A list of available options can be found below in the :ref:`options section
+<options>`.
+
+Defaults for these options can also be set by creating a file named
+``jupyter_server_config.py`` in your Jupyter folder. The Jupyter
+folder is in your home directory, ``~/.jupyter``.
+
+To create a ``jupyter_server_config.py`` file, with all the defaults
+commented out, you can use the following command line::
+
+  $ jupyter server --generate-config
+
+
+.. _options:
+
+Options
+-------
+
+This list of options can be generated by running the following and hitting
+enter::
+
+  $ jupyter server --help-all
+
+"""
+
 
 def setup(app):
     dest = osp.join(HERE, "other", "changelog.md")
     shutil.copy(osp.join(HERE, "..", "..", "CHANGELOG.md"), dest)
+
+    # Generate full-config docs.
+    from jupyter_server.serverapp import ServerApp
+
+    destination = os.path.join(HERE, "other/full-config.rst")
+    with open(destination, "w") as f:
+        f.write(CONFIG_HEADER)
+        f.write(ServerApp().document_config_options())

docs/source/conf.py

@@ -2,7 +2,7 @@
 import pwd
 from getpass import getuser
 
-from pamela import PAMError, authenticate
+from pamela import PAMError, authenticate  # type:ignore
 
 from jupyter_server.auth.identity import IdentityProvider, User
 

examples/identity/system_password/jupyter_server_config.py

@@ -11,7 +11,7 @@
 from time import monotonic
 from typing import Any, Dict, Optional
 
-import websocket
+import websocket  # type:ignore
 from jupyter_client.asynchronous.client import AsyncKernelClient
 from jupyter_client.clientabc import KernelClientABC
 from jupyter_client.kernelspec import KernelSpecManager

jupyter_server/gateway/managers.py

@@ -55,11 +55,11 @@ def open(self):
         """Routes events that are emitted by Jupyter Server's
         EventBus to a WebSocket client in the browser.
         """
-        self.event_logger.add_listener(listener=self.event_listener)
+        self.event_logger.add_listener(listener=self.event_listener)  # type:ignore[arg-type]
 
     def on_close(self):
         """Handle a socket close."""
-        self.event_logger.remove_listener(listener=self.event_listener)
+        self.event_logger.remove_listener(listener=self.event_listener)  # type:ignore[arg-type]
 
 
 def validate_model(data: Dict[str, Any]) -> None:

jupyter_server/services/events/handlers.py

@@ -14,7 +14,7 @@
     import sqlite3
 except ImportError:
     # fallback on pysqlite2 if Python was build without sqlite
-    from pysqlite2 import dbapi2 as sqlite3  # type:ignore[no-redef]
+    from pysqlite2 import dbapi2 as sqlite3  # type:ignore
 
 from dataclasses import dataclass, fields
 

jupyter_server/services/sessions/sessionmanager.py

@@ -2,7 +2,7 @@
 import warnings
 
 # Shims
-from jupyter_server_terminals import api_handlers, initialize  # noqa
+from jupyter_server_terminals import api_handlers  # noqa
 from jupyter_server_terminals.handlers import TermSocket  # noqa
 from jupyter_server_terminals.terminalmanager import TerminalManager  # noqa
 
@@ -11,3 +11,7 @@
     DeprecationWarning,
     stacklevel=2,
 )
+
+
+def initialize(webapp, root_dir, connection_url, settings):
+    """Included for backward compat, but no-op."""

jupyter_server/terminal/__init__.py

@@ -1,2 +1,6 @@
 """Terminal API handlers."""
-from jupyter_server_terminals import TerminalAPIHandler, TerminalHandler, TerminalRootHandler
+from jupyter_server_terminals.api_handlers import (
+    TerminalAPIHandler,
+    TerminalHandler,
+    TerminalRootHandler,
+)

jupyter_server/terminal/api_handlers.py

@@ -4,4 +4,4 @@
 """
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
-from jupyter_server_terminals import TerminalManager  # noqa
+from jupyter_server_terminals.terminalmanager import TerminalManager  # noqa

jupyter_server/terminal/terminalmanager.py

@@ -20,7 +20,7 @@
 )
 from urllib.request import pathname2url  # noqa: F401
 
-from _frozen_importlib_external import _NamespacePath
+from _frozen_importlib_external import _NamespacePath  # type:ignore
 from jupyter_core.utils import ensure_async
 from packaging.version import Version
 from tornado.httpclient import AsyncHTTPClient, HTTPClient, HTTPRequest

jupyter_server/utils.py

@@ -229,7 +229,8 @@ filterwarnings = [
   "ignore:run_pre_save_hook is deprecated:DeprecationWarning",
   "always:unclosed <socket.socket:ResourceWarning",
   "module:Jupyter is migrating its paths to use standard platformdirs:DeprecationWarning",
-  "ignore:jupyter_server.base.zmqhandlers module is deprecated in Jupyter Server 2.0:DeprecationWarning"
+  "ignore:jupyter_server.base.zmqhandlers module is deprecated in Jupyter Server 2.0:DeprecationWarning",
+  "ignore:zmq.eventloop.ioloop is deprecated in pyzmq 17:DeprecationWarning",
 ]
 
 [tool.coverage.report]
@@ -268,18 +269,6 @@ warn_redundant_casts = true
 explicit_package_bases = true
 namespace_packages = true
 
-[[tool.mypy.overrides]]
-module = [
-    "pamela",
-    "pysqlite2",
-    "jupyter_events.*",
-    "jupyter_server_terminals.*",
-    "_frozen_importlib_external",
-    "send2trash",
-    "websocket"
-]
-ignore_missing_imports = true
-
 [tool.interrogate]
 ignore-init-module=true
 ignore-private=true

pyproject.toml

@@ -4,6 +4,7 @@
 import shlex
 import shutil
 import sys
+import warnings
 
 import pytest
 from tornado.httpclient import HTTPClientError
@@ -291,3 +292,12 @@ def test_shell_command_override(
         )
     else:
         assert app.web_app.settings["terminal_manager"].shell_command == expected_shell
+
+
+def test_importing_shims():
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        from jupyter_server.terminal import initialize  # noqa
+        from jupyter_server.terminal.api_handlers import TerminalRootHandler  # noqa
+        from jupyter_server.terminal.handlers import TermSocket  # noqa
+        from jupyter_server.terminal.terminalmanager import TerminalManager  # noqa