`Test Docs` started failing on `main`

[krassowski]

As seen in https://github.com/jupyter-server/jupyter_server/actions/runs/21582281482/job/62182006414.

• Last passing: 15th Jan 2026
• First failing: 16th Jan 20206

WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.serverapp.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.serverapp.Environment": name 'te' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.auth.identity.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.auth.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.base.handlers.TemplateNotFound": name 'Undefined' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.extension.application.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.extension.application.Environment": name 'te' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.extension.handler.TemplateNotFound": name 'Undefined' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.extension.manager.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.services.contents.manager.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.services.kernels.kernelmanager.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]
WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.services.kernels.connection.channels.Dict": name 'K' is not defined [sphinx_autodoc_typehints.forward_reference]

Noted in #1594.

[krassowski]

Most likely due to new versions sphinx/sphinx-autodoc-typehints being pulled in:

docutils: 0.21.2 → 0.22.4
markdown-it-py: 3.0.0 → 4.0.0
myst-parser: 4.0.1 → 5.0.0
sphinx: 8.2.3 → 9.1.0
sphinx-autodoc-typehints: 3.5.2 → 3.6.2

[krassowski]

Upstream issues:

• “Cannot resolve forward reference” when using a type variable defined by Python 3.12 type syntax tox-dev/sphinx-autodoc-typehints#580
• Calling typing.get_type_hints with a class or instance method with PEP 695 type parameters fails if PEP 563 is enabled python/cpython#124089

[krassowski]

It sounds like we have four options:

• a) use old-style typing.TypeVar syntax
• b) remove from __future__ import annotations
• c) downgrade to sphinx 8.x and sphinx-autodoc-typehints 3.5.x
• d) disable these warnings

It seems like in many cases changes would need to be made upstream, e.g. in jinja2 or traitlets. Maybe this is yet another upstream bug in sphinx-autodoc-typehints but for:

WARNING: Cannot resolve forward reference in type annotations of "jupyter_server.extension.application.Environment": name 'te' is not defined [sphinx_autodoc_typehints.forward_reference]

the only Environment occurrence is:

jupyter_server/jupyter_server/extension/application.py

Line 10 in df624c0

from jinja2 import Environment, FileSystemLoader

and

jupyter_server/jupyter_server/extension/application.py

Lines 101 to 106 in df624c0

	self.jinja2_env = Environment(
	loader=FileSystemLoader(self.template_paths),
	extensions=["jinja2.ext.i18n"],
	autoescape=True,
	**self.jinja2_options,
	)

jinja2 defines te as an alias for typing extensions and uses it like this:

if t.TYPE_CHECKING:
    import typing_extensions as te

newline_sequence: "te.Literal['\\n', '\\r\\n', '\\r']"