sphinx-immaterial uses some more private-leaning methods and functions from sphinx

As for using private APi in sphinx, we really can't avoid this without removing some theme-specific features. It would nice if we didn't have to, but Sphinx domains are a bit rigid. See #113 (comment)

ImportError: cannot import name 'PyTypedField' from 'sphinx.domains.python'

As for this, I don't see PyTypedField on the list of Deprecated API. I do see that it is now re-exported in v7.3.5.

@AA-Turner I don't think it was a good idea to move public API into private modules. That move tells me that only sphinx.ext.* is allowed to use those API members, which is not very practical. Think about all the other third-party sphinx extensions posing an alternative implementation to autodoc (and not just for the python domain).

AttributeError: module 'sphinx.domains.cpp' has no attribute 'ASTOperator'

It looks like the domain refactor in sphinx-doc/sphinx@v7.2.6...v7.3.5 was not specific to just the python domain. Our docs now fail (with v7.3.5) about cpp domain as well. This one might take us a while to resolve...

I was able to get a sphinx-immaterial build working nominally with just an import of most/all things removed in pre 7.3.0 sphinx.domains.{c,cop,python}, sphinx-doc/sphinx#12297, so that's hopeful that the issue is restricted to a subset of those changes.

You'll need to change

to

try:
    if sphinx.version_info >= (7, 3):
        sphinx.domains.python._annotation._parse_arglist = parse_arglist
        sphinx.domains.python._object._parse_arglist = parse_arglist
    else:
        sphinx.domains.python._parse_arglist = parse_arglist
except AttributeError:
    # log some warning rather than crashing

Sphinx 7.3.6 has been released with fixes.

A

jinja_context conains the module sys as a value

pickling environment... WARNING: cannot cache unpickable configuration value: 'jinja_contexts' (because it contains a function, class, or module object)

This poses a problem in

Other jinja_context["sys"] usage is in

Geez. Even the typing for public API changed quite significantly.

Sphinx.add_config_value (sphinx-doc/sphinx@259118d)

• no longer takes a bool | str as the rebuild param (didn't know that usage was deprecated -- its not in the deprecated list)
• now uses narrow typing for the types param. According to mypy, all our specified types are wrong (even though they work with v7.3.x)

I'm not going to lie. This one is a pain in the ass. There's usually one or two things we need to update for a minor version bump... 😞 Also, v7.3 is ripe with merge commits in the master branch (which makes it harder to git blame a PR or instigating issue when looking for rationality). It would be a good idea to start putting a reference to a discussion (PR or issue) in the merge commit's description.

Thank you for the feedback, Brendan (@2bndy5).

Even the typing for [Sphinx.add_config_value] changed quite significantly.

The intent here was to make the type hints (intended usage) stricter, whilst the runtime acceptable values didn't change. Any examples of mypy failing would be useful.

Sphinx.add_config_value no longer takes a bool | str as the rebuild param

It still does at runtime, the static typing information has become stricter, though, to reflect intended use.

Sphinx.add_config_value now uses narrow typing for the types param.
According to mypy, all our specified types are wrong (even though they work with v7.3.x)

All previously valid values should still be valid. I'm happy to tweak the type hints if needed (suggestions welcome).

A

All previously valid values should still be valid. I'm happy to tweak the type hints if needed (suggestions welcome).

I don't think Collection[type] satisfies the previous use cases. I got errors saying

error: Argument "types" to "add_config_value" of "Sphinx" has incompatible
type "tuple[type[bool], type[None]]"; expected "type | Collection[type] | ENUM"  [arg-type]
            types=(bool, type(None)),
                  ^~~~~~~~~~~~~~~~~~

When I change Collection[type] to Sequence[type], I no longer get this error from mypy. For now, I've just type: ignored any of our usage that doesn't satisfy Collection[type].

Collection ought be more general than Sequence (as e.g. a set is a Collection but not a Sequence).

Mypy runs fine for me on the first two of the below three test-cases, and only reports an error for the third -- I suspect this might actually be an error with Mypy's implementation/special casing of NoneType? Certainly from a type theory perspective I think the annotations in add_config_value are correct.

from sphinx.application import Sphinx


def setup(app: Sphinx) -> None:
    app.add_config_value(
        'spam',
        None,
        '',
        (bool, str, type(None))
    )
    app.add_config_value(
        'ham',
        None,
        '',
        (bool, str)
    )
    app.add_config_value(
        'ham',
        None,
        '',
        (bool, type(None))  # mypy error: incompatible type ...
    )

Sorry to cause trouble, though, it isn't intended and thank you for your co-operation in trying to improve the situation.

A

Thanks for your consideration. For passers by, this error was reported with mypy v1.8.0 and v1.9.0.