Update docs version

[adamgayoso]

built docs

1. lower bound the theme version so that we get dark mode!
2. Use sphinx ext autodoc for typehint processing instead of sphinx-autodoc-typehints which we borrowed from scanpy at a time when sphinx didn't have this functionality. The third-party package also started processing numpydoctring return sections differently resulting in a colon in front of our custom freeform return
3. Edited the autosummary class template to remove headers for attr/meth names, which aren't necessary. Without this it looks like this on the right sidebar:

[github-actions]

A PR has been generated to the instance repo:
scverse/cookiecutter-scverse-instance#42

You can check out the PR to preview your changes
in an instance of the cookiecutter template. The PR will be kept in sync with
this PR automatically.

[flying-sheep]

sphinx.ext.autodoc’s typehint support is not yet ready for prime time, as it obtains type hints by parsing signatures and can’t deal with parameter defaults whose reprs aren’t valid Python code (e.g. every function, every object of a user defined class without __repr__ method, enum members, …). I’m not sure if that only applies to autodoc_typehints = 'signature' (which we don’t use) or all of them, in which case it’s a dealbreaker. If it breaks, we should continue to use sphinx-autodoc-typehints (without scanpydoc’s by-now-unnecessary customization).

I used autodoc_typehints = 'signature' for a little package I maintain, and had to hack around its limitations in two instances, which is too much. E.g. I had to turn this wonderfully reasonable definition:

from operator import add
from collections.abc import Iterable, Callable
from typing import TypeVar

A = TypeVar("A")
T = TypeVar("T")

class accumulate(...)
    def __init__(iterable: Iterable[A], func: Callable[[A, A], T] = add) -> None:
        ...

into this monstrosity to keep sphinx.ext.autodocs from choking:

...

class _Adder:
    """This just exists to allow Sphinx to parse the function signature."""

    def __call__(self, a: A, b: A) -> T:
        a + b

    def __repr__(self) -> str:
        return "add"  # pragma: no cover

class accumulate(...)
    def __init__(iterable: Iterable[A], func: Callable[[A, A], T] = _Adder()) -> None:
        ...

[adamgayoso]

@flying-sheep happy to keep sphinx autodoc typehints, but would you be able to update the typed returns extension on this repo?

This PR on sphinx autodoc typehints tox-dev/sphinx-autodoc-typehints#311 causes an issue where : precedes all return descriptions.

[flying-sheep]

I’ll check out the return problem. But before I do that: I can’t find the issue you filed to sphinx-autodoc-typehints’ repo about this problem, can you link it to me?

I investigated further, and while using 'description' helps with the problem I described, it doesn’t fix other problems like spurios “class not found” errors when using TypeVars. sphinx-autodoc-typehints is just more mature right now.

• autodoc-documented type aliases can't be referenced from type annotations sphinx-doc/sphinx#10785
• sphinx.ext.autodoc: Typehints, aliases, and (internal/external) cross-references sphinx-doc/sphinx#10794

Comparison:

sphinx-autodoc-typehints	autodoc_typehints = "description"
no log errors

I think neither style is good. sphinx-autodoc-typehints is too visually busy, and autodoc_typehints = "description" breaks the otherwise consistent visual style for references to functions, classes, …

[adamgayoso]

I didn't file an issue because the problem seems to be more specific to our custom typed returns extension, which is in this repo/scanpy/etc. You can see the "bug" in the left image above: : Some integer value

I can remove the change in this PR, but we should figure something out with the : issue.

[flying-sheep]

Ah I see! Regarding the colon, since we know which PR it comes from and that it’s just there instead of being indicative of a deeper problem, we can simply remove it, right?

We should move that little typed-returns customization to scanpydoc and test it properly, but for now, I’ll just fix it here.