How to properly escape `*` and `_` when rendering docs with Sphinx about jaxtyping

[jeertmans]

Ok, nevermind, the not all was caused by the fact that I use from __future__ import annotations in my plotting module. In module where I do not import from __future__ import annotations, it renders nicely.

[patrick-kidger]

Ah, that's good to know! For what it's worth from __future__ import annotations will often break runtime type checkers in unpredictable ways (resolving the stringified annotations correctly is intractable in general), so I'm afraid this should be avoided anyway.

(That aside, if this is a greenfield project then having tried both Sphinx and MkDocs, I've come to really enjoy the greater simplicity of the latter, and would recommend it!)

[jeertmans]

I actually run in a problem where not solution is optimal because of that.

Because I use this library, I cannot use from __future__ import annotations.

When Sphinx's autodoc tries to import the module, it first tries with typing.TYPE_CHECKING=True, so I could do that:

if TYPE_CHECKING:
    from some_optioal_deps import ReturnType
else:
    ReturnType = Any

but will fail (Any will be displayed in the docs) because your module depends on numpy, which cannot be imported with TYPE_CHECKING set to True. It then fallsback to ReturnType = Any.

So the solution I came up with is

try:
    from some_optioal_deps import ReturnType
except ImportError:
    ReturnType = Any

which renders correctly in the docs (because I installed the optional deps to build the docs).

However, tools like Pyright will complain because ReturnType can be Any, which is often a bad practice.

My current solution was to annotate each return type with # type: ignore.

I think you could "fix" this issue by removing imports to NumPy load, and only import this when needed.

Anything, I thought it was interesting to document this here!