Sphinx v9.0 breaks theme

[2bndy5]

Testing the sphinx 9.0.0-rc2 with this theme crashes with the following error:

Traceback
=========

      File "C:\dev\sphinx-immaterial\.venv\Lib\site-packages\sphinx\builders\__init__.py", line 427, in build
        pickle.dump(self.env, f, pickle.HIGHEST_PROTOCOL)
        ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    _pickle.PicklingError: Can't pickle local object <class 'sphinx_immaterial._get_html_builder.<locals>.CustomHTMLBuilder'>
    when serializing dict item '_builder_cls'
    when serializing sphinx.environment.BuildEnvironment state
    when serializing sphinx.environment.BuildEnvironment object

It seems the changes in sphinx v9.0 no longer like our dynamic HTML Builder class (declarated in function body). After moving the class definition outside the function body, it complained about our custom node visitor (which is also defined in a function body):

Traceback
=========

      File "C:\dev\sphinx-immaterial\.venv\Lib\site-packages\sphinx\transforms\post_transforms\__init__.py", line 352, in run
        if issubclass(translator, SphinxTranslator):
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    TypeError: issubclass() arg 1 must be a class

[AA-Turner]

@2bndy5 are you able to run a git bisect? I can't immediately recall any relevant changes...

A

[jbms]

That shouldn't be getting pickled, so we should figure out why it is getting picked up now.

[2bndy5]

I looked at the git blame for the line about pickling the builder env:
https://github.com/sphinx-doc/sphinx/blob/718fae024531603bb45c96af6c9d33615bdf42c8/sphinx/builders/__init__.py#L427

But I didn't see anything recent that would point to some change in v9.0. If the builder env was not getting pickled before v9.0, then we should probably focus on the condition that causes the env to get pickled: if updated_docnames:.

FWIW, I have been flushing all old build artifacts before running sphinx-build. But I still get the error when a successful docs build (from v8.x) still exists (with no docs changes made since).

[2bndy5]

According to the changelog:

sphinx-doc/sphinx#13751, sphinx-doc/sphinx#14089: sphinx.ext.autodoc has been substantially rewritten, and there may be some incompatible changes in edge cases, especially when extensions interact with autodoc internals.

This is what initially worried me. We heavily use autodoc internals to improve the user experience and provide our own apigen extensions. If I had to guess, I'd say something in this area is causing updated_docnames to become True.

[AA-Turner]

A bisect shows the below. The relevant change is adding the BuildEnvironment._builder_cls attribute:

• https://github.com/sphinx-doc/sphinx/blob/v9.0.0rc2/sphinx/environment/__init__.py#L112-L113
• https://github.com/sphinx-doc/sphinx/blob/v9.0.0rc2/sphinx/application.py#L414

21c8513e49d4827aef5602964c3d892bbdc06d0d is the first bad commit
commit 21c8513e49d4827aef5602964c3d892bbdc06d0d (refs/bisect/bad)
Author: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Date:   Sat Jun 7 16:12:47 2025 +0100

    Avoid ``self.app`` in transforms (#13628)

 sphinx/application.py                              |  2 +
 sphinx/builders/linkcheck.py                       |  4 +-
 sphinx/environment/__init__.py                     |  3 +
 sphinx/ext/extlinks.py                             |  2 +-
 sphinx/ext/viewcode.py                             | 12 ++--
 sphinx/io.py                                       | 35 +-----------
 sphinx/transforms/__init__.py                      |  7 ++-
 sphinx/transforms/i18n.py                          | 66 +++++++++++++++++-----
 sphinx/transforms/post_transforms/__init__.py      | 17 +++---
 sphinx/transforms/post_transforms/images.py        | 18 +++---
 .../test_transforms_post_transforms_images.py      |  2 +-
 11 files changed, 91 insertions(+), 77 deletions(-)

[AA-Turner]

I have a fix for the pickle problem (edit: sphinx-doc/sphinx#14123).

The second issue @2bndy5 found I think should be fixed in sphinx-immaterial. Sphinx treats Builder.default_translator_class as a ClassVar, but CustomHTMLBuilder.default_translator_class is an instance variable (property). The changes (in the same commit as above) mean that Sphinx now looks up the default translator class on the builder type (env._builder_cls), rather than the builder instance.

sphinx-immaterial/sphinx_immaterial/__init__.py

Lines 71 to 75 in 9fda271

	@property
	def default_translator_class(self):
	return html_translator_mixin.get_html_translator(
	super().default_translator_class
	)

A

[2bndy5]

Thanks @AA-Turner for #476 and sphinx-doc/sphinx#14123. Now I'm just getting warnings about :ref: roles that target external references (mostly from sphinx-inventories fetched by sphinx.ext.intersphinx, some for references that are defined in other doc pages within the same project):

Local build log

Running Sphinx v9.0.0rc3
loading translations [en]... done
[1/2] Loading JSON schema: apidoc/json/index_transform_schema.yml
[2/2] Loading JSON schema: apidoc/json/inheritance_schema.yml
Parsed C++ input in 0.27536 seconds
Found 19 C++ declarations
myst v4.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'smartquotes', 'attrs_inline', 'replacements', 'fieldlist', 'strikethrough', 'tasklist', 'substitution', 'deflist', 'attrs_block'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={role: ...}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=True, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 49 source files that are out of date
updating environment: [new config] 49 added, 0 changed, 0 removed
reading sources... [100%] theme_result
C:\dev\sphinx-immaterial\docs\apidoc\cpp\apigen.rst.rst:107: WARNING: No Python entity named: 'tensorstore_demo.IndexDomain.__init__(json)'
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst.rst:166: WARNING: No top-level Python API group named: 'some-other-group', valid groups are: []
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst.rst:192: WARNING: No Python entity named: 'tensorstore_demo.IndexDomain.__init__(json)'
C:\dev\sphinx-immaterial\docs\customization.rst:195: WARNING: inventory for external cross-reference not found: 'sphinx_docs' [intersphinx.external]
C:\dev\sphinx-immaterial\docs\customization.rst:201: WARNING: inventory for external cross-reference not found: 'sphinx_docs' [intersphinx.external]
C:\dev\sphinx-immaterial\docs\python_apigen_demo.rst.rst:7: WARNING: No top-level Python API group named: 'indexing', valid groups are: []
C:\dev\sphinx-immaterial\docs\python_apigen_demo.rst.rst:12: WARNING: No top-level Python API group named: 'some-other-group', valid groups are: []
C:\dev\sphinx-immaterial\docs\python_apigen_demo.rst.rst:17: WARNING: No top-level Python API group named: 'type-param', valid groups are: []
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files...
Writing evaluated template result to C:\dev\sphinx-immaterial\docs\_build\html\_static\basic.css
Writing evaluated template result to C:\dev\sphinx-immaterial\docs\_build\html\_static\documentation_options.js
Writing evaluated template result to C:\dev\sphinx-immaterial\docs\_build\html\_static\language_data.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] theme_result
C:\dev\sphinx-immaterial\docs\additional_samples.rst:240: WARNING: 'any' reference target not found: productionlist [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:33: WARNING: 'any' reference target not found: seealso [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:33: WARNING: 'any' reference target not found: todo [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:60: WARNING: 'any' reference target not found: versionadded [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:60: WARNING: 'any' reference target not found: versionchanged [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:60: WARNING: 'any' reference target not found: deprecated [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:60: WARNING: 'any' reference target not found: versionremoved [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:95: WARNING: 'any' reference target not found: versionchanged [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:259: WARNING: 'any' reference target not found: ref [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:293: WARNING: 'any' reference target not found: list [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:293: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:293: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\admonitions.rst:417: WARNING: 'any' reference target not found: note [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\cpp\apigen.rst:158: WARNING: rst:dir reference target not found: highlight [ref.dir]
C:\dev\sphinx-immaterial\docs\apidoc\cpp\external_cpp_references.rst:4: WARNING: rst:role reference target not found: cpp:expr [ref.role]
C:\dev\sphinx-immaterial\docs\apidoc\cpp\external_cpp_references.rst:4: WARNING: 'any' reference target not found: sphinx.ext.intersphinx [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\cpp\index.rst:37: WARNING: rst:role reference target not found: cpp:expr [ref.role]
C:\dev\sphinx-immaterial\docs\apidoc\cpp\index.rst:37: WARNING: rst:role reference target not found: cpp:texpr [ref.role]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:10: WARNING: 'confval' reference target not found: maximum_signature_line_length [ref.confval]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:20: WARNING: 'confval' reference target not found: maximum_signature_line_length [ref.confval]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:31: WARNING: 'confval' reference target not found: maximum_signature_line_length [ref.confval]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:69: WARNING: 'confval' reference target not found: maximum_signature_line_length [ref.confval]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:74: WARNING: 'confval' reference target not found: maximum_signature_line_length [ref.confval]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:203: WARNING: py:class reference target not found: collections.abc.MutableMapping [ref.class]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:203: WARNING: py:class reference target not found: numbers.Real [ref.class]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:203: WARNING: py:class reference target not found: collections.abc.MutableMapping [ref.class]
C:\dev\sphinx-immaterial\docs\apidoc\format_signatures.rst:203: WARNING: py:class reference target not found: numbers.Real [ref.class]
C:\dev\sphinx-immaterial\docs\apidoc\index.rst:63: WARNING: py:obj reference target not found: sphinx.application.Sphinx.add_object_type [ref.obj]
C:\dev\sphinx-immaterial\docs\apidoc\index.rst:89: WARNING: py:obj reference target not found: sphinx.application.Sphinx.add_object_type [ref.obj]
C:\dev\sphinx-immaterial\docs\apidoc\json\domain.rst:40: WARNING: py:obj reference target not found: glob [ref.obj]
C:\dev\sphinx-immaterial\docs\apidoc\json\domain.rst:65: WARNING: rst:dir reference target not found: highlight [ref.dir]
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst:73: WARNING: py:obj reference target not found: sphinx.ext.napoleon [ref.obj]
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst:112: WARNING: py:obj reference target not found: sphinx.ext.napoleon [ref.obj]
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst:198: WARNING: 'any' reference target not found: rst-sections [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst:440: WARNING: rst:dir reference target not found: highlight [ref.dir]
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst:506: WARNING: 'any' reference target not found: sphinx.ext.autodoc [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst:509: WARNING: 'any' reference target not found: autodoc-process-bases [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:149: WARNING: py:class reference target not found: tensorstore_demo.Dim [ref.class]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:156: WARNING: 'confval' reference target not found: python_use_unqualified_type_names [ref.confval]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:165: WARNING: 'any' reference target not found: None [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:188: WARNING: rst:dir reference target not found: py:property [ref.dir]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:204: WARNING: 'any' reference target not found: int [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:204: WARNING: 'any' reference target not found: float [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:204: WARNING: 'any' reference target not found: str [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:225: WARNING: 'any' reference target not found: int [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:225: WARNING: 'any' reference target not found: float [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:230: WARNING: 'any' reference target not found: str [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:246: WARNING: 'any' reference target not found: sphinx.ext.autodoc [ref.any]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:307: WARNING: py:class reference target not found: collections.abc.Sequence [ref.class]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:307: WARNING: py:class reference target not found: tensorstore_demo.DimensionSelection [ref.class]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:10: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:10: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:10: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:10: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:32: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:32: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:60: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_annotations.rst:110: WARNING: 'any' reference target not found: code-block [ref.any]
C:\dev\sphinx-immaterial\docs\code_syntax_highlighting.rst:38: WARNING: rst:dir reference target not found: highlight [ref.dir]
C:\dev\sphinx-immaterial\docs\code_syntax_highlighting.rst:67: WARNING: rst:dir reference target not found: highlight [ref.dir]
C:\dev\sphinx-immaterial\docs\content_tabs.rst:31: WARNING: 'any' reference target not found: ref [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:15: WARNING: undefined label: 'metadata' [ref.ref]
C:\dev\sphinx-immaterial\docs\customization.rst:19: WARNING: undefined label: 'metadata' [ref.ref]
C:\dev\sphinx-immaterial\docs\customization.rst:166: WARNING: 'any' reference target not found: html_favicon [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:172: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:207: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:326: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:375: WARNING: rst:dir reference target not found: code-block [ref.dir]
C:\dev\sphinx-immaterial\docs\customization.rst:412: WARNING: py:mod reference target not found: sphinx.ext.intersphinx [ref.mod]
C:\dev\sphinx-immaterial\docs\customization.rst:427: WARNING: 'any' reference target not found: toctree [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:427: WARNING: 'any' reference target not found: toctree [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:427: WARNING: 'any' reference target not found: toctree [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:491: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:491: WARNING: 'any' reference target not found: list [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:491: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:491: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:596: WARNING: 'any' reference target not found: list [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:596: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:691: WARNING: 'any' reference target not found: html_css_files [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:743: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:750: WARNING: 'any' reference target not found: list [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:750: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:750: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:802: WARNING: 'any' reference target not found: False [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:833: WARNING: 'any' reference target not found: list [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:833: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:833: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:850: WARNING: 'any' reference target not found: bool [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:967: WARNING: py:class reference target not found: concurrent.futures.ThreadPoolExecutor [ref.class]
C:\dev\sphinx-immaterial\docs\customization.rst:1007: WARNING: 'any' reference target not found: True [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:1021: WARNING: 'any' reference target not found: list [ref.any]
C:\dev\sphinx-immaterial\docs\customization.rst:1114: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\demo_api.rst:144: WARNING: rst:role reference target not found: cpp:expr [ref.role]
C:\dev\sphinx-immaterial\docs\demo_api.rst:223: WARNING: 'any' reference target not found: html_use_index [ref.any]
C:\dev\sphinx-immaterial\docs\graphviz.rst:4: WARNING: py:mod reference target not found: sphinx.ext.graphviz [ref.mod]
C:\dev\sphinx-immaterial\docs\graphviz.rst:39: WARNING: 'confval' reference target not found: graphviz_dot [ref.confval]
C:\dev\sphinx-immaterial\docs\graphviz.rst:39: WARNING: 'confval' reference target not found: graphviz_dot_args [ref.confval]
C:\dev\sphinx-immaterial\docs\graphviz.rst:39: WARNING: py:mod reference target not found: sphinx.ext.graphviz [ref.mod]
C:\dev\sphinx-immaterial\docs\graphviz.rst:44: WARNING: 'confval' reference target not found: graphviz_output_format [ref.confval]
C:\dev\sphinx-immaterial\docs\graphviz.rst:70: WARNING: rst:dir reference target not found: graphviz [ref.dir]
C:\dev\sphinx-immaterial\docs\graphviz.rst:94: WARNING: py:obj reference target not found: tensorstore_demo.DimensionSelection [ref.obj]
C:\dev\sphinx-immaterial\docs\graphviz.rst:115: WARNING: py:obj reference target not found: sphinx.builders.latex.LaTeXBuilder [ref.obj]
C:\dev\sphinx-immaterial\docs\inline_icons.rst:27: WARNING: 'any' reference target not found: list [ref.any]
C:\dev\sphinx-immaterial\docs\inline_icons.rst:35: WARNING: 'any' reference target not found: html_static_path [ref.any]
C:\dev\sphinx-immaterial\docs\keys.rst:8: WARNING: rst:role reference target not found: kbd [ref.role]
C:\dev\sphinx-immaterial\docs\keys.rst:90: WARNING: 'any' reference target not found: bool [ref.any]
C:\dev\sphinx-immaterial\docs\keys.rst:90: WARNING: 'any' reference target not found: False [ref.any]
C:\dev\sphinx-immaterial\docs\keys.rst:95: WARNING: 'any' reference target not found: str [ref.any]
C:\dev\sphinx-immaterial\docs\keys.rst:102: WARNING: 'any' reference target not found: str [ref.any]
C:\dev\sphinx-immaterial\docs\keys.rst:108: WARNING: 'any' reference target not found: dict [ref.any]
C:\dev\sphinx-immaterial\docs\keys.rst:113: WARNING: 'any' reference target not found: str [ref.any]
C:\dev\sphinx-immaterial\docs\keys.rst:126: WARNING: 'any' reference target not found: str [ref.any]
C:\dev\sphinx-immaterial\docs\mermaid_diagrams.rst:37: WARNING: 'any' reference target not found: ref [ref.any]
C:\dev\sphinx-immaterial\docs\myst_typography.md:33: WARNING: 'myst' cross-reference target not found: 'syntax/attributes/block' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:44: WARNING: 'myst' cross-reference target not found: 'organising-content' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:46: WARNING: 'myst' cross-reference target not found: 'syntax/referencing' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:53: WARNING: 'myst' cross-reference target not found: 'syntax/attributes/block' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:86: WARNING: 'myst' cross-reference target not found: 'syntax/strikethrough' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:92: WARNING: 'myst' cross-reference target not found: 'syntax/smartquotes' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:92: WARNING: 'myst' cross-reference target not found: 'syntax/replacements' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:100: WARNING: 'myst' cross-reference target not found: 'syntax/attributes/inline' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:139: WARNING: 'myst' cross-reference target not found: 'syntax/attributes/block' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:161: WARNING: 'myst' cross-reference target not found: 'syntax/tasklists' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:171: WARNING: 'myst' cross-reference target not found: 'syntax/roles' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:186: WARNING: 'myst' cross-reference target not found: 'syntax/attributes/block' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:196: WARNING: 'myst' cross-reference target not found: 'syntax/definition-lists' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:212: WARNING: 'myst' cross-reference target not found: 'syntax/attributes/block' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:212: WARNING: 'myst' cross-reference target not found: 'syntax/roles' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\myst_typography.md:225: WARNING: 'myst' cross-reference target not found: 'syntax/fieldlists' [myst.xref_missing]
C:\dev\sphinx-immaterial\docs\rst_basics.rst:193: WARNING: rst:dir reference target not found: highlight [ref.dir]
C:\dev\sphinx-immaterial\docs\rst_basics.rst:193: WARNING: 'confval' reference target not found: highlight_language [ref.confval]
C:\dev\sphinx-immaterial\docs\rst_basics.rst:193: WARNING: rst:dir reference target not found: code-block [ref.dir]
C:\dev\sphinx-immaterial\docs\rst_basics.rst:501: WARNING: 'confval' reference target not found: default_role [ref.confval]
C:\dev\sphinx-immaterial\docs\rst_basics.rst:631: WARNING: 'confval' reference target not found: rst_prolog [ref.confval]
C:\dev\sphinx-immaterial\docs\rst_basics.rst:631: WARNING: 'confval' reference target not found: rst_epilog [ref.confval]
C:\dev\sphinx-immaterial\docs\rst_basics.rst:700: WARNING: 'confval' reference target not found: source_encoding [ref.confval]
C:\dev\sphinx-immaterial\docs\task_lists.rst:62: WARNING: 'any' reference target not found: bool [ref.any]
C:\dev\sphinx-immaterial\docs\task_lists.rst:62: WARNING: 'any' reference target not found: False [ref.any]
C:\dev\sphinx-immaterial\docs\task_lists.rst:66: WARNING: 'any' reference target not found: bool [ref.any]
C:\dev\sphinx-immaterial\docs\task_lists.rst:66: WARNING: 'any' reference target not found: False [ref.any]
C:\dev\sphinx-immaterial\docs\task_lists.rst:119: WARNING: 'any' reference target not found: ref [ref.any]
C:\dev\sphinx-immaterial\docs\task_lists.rst:125: WARNING: 'any' reference target not found: False [ref.any]
C:\dev\sphinx-immaterial\docs\task_lists.rst:130: WARNING: 'any' reference target not found: False [ref.any]
C:\dev\sphinx-immaterial\docs\theme_result.rst:213: WARNING: external std:doc reference target not found: syntax/roles-and-directives [ref.doc]
generating indices... genindex py-modindex done
highlighting module code... [100%] test_py_module.test
writing additional pages... done
copying images... [100%] rst-cheatsheet/sharealike.png
dumping search index in English (code: en)... done
dumping object inventory... done
Generating sitemap for 58 pages in C:\dev\sphinx-immaterial\docs\_build\html/sitemap.xml
build succeeded, 152 warnings.

[AA-Turner]

sphinx-doc/sphinx#13751, sphinx-doc/sphinx#14089: sphinx.ext.autodoc has been substantially rewritten, and there may be some incompatible changes in edge cases, especially when extensions interact with autodoc internals.

This is what initially worried me. We heavily use autodoc internals to improve the user experience and provide our own apigen extensions.

Thoughts on the autodoc rewrite front @jbms @2bndy5:

• You may want to enable autodoc_use_legacy_class_based for all users of your theme, at least initially.
• That option is intended to transparently use the 'legacy' implementation, although the files have moved to sphinx.ext.autodoc._legacy_class_based (may be relevant for monkeypatching).
• The new implementation uses a new _ItemProps class & a largely functional approach, contained in the new underscore-prefixed modules of autodoc. For ease of maintenence upstream I intend for the entire new implementation to be private, which may impact monkeypatching.
• I'm very open to changes in the new autodoc implementation to make things easier for sphinx-immaterial, or upstreamed patches etc. Also happy to consider e.g. new autodoc events.
• Likewise very happy to take bug reports on extensibility.

A

[2bndy5]

I just tried with sphinx 9.0.0rc4 and the most of the :ref: warnings went away. But there's still some warnings related to our apigen extensions.

Local build log

Running Sphinx v9.0.0rc4
loading translations [en]... done
making output directory... done
loading intersphinx inventory 'python' from https://docs.python.org/3/objects.inv ...
loading intersphinx inventory 'sphinx_docs' from https://www.sphinx-doc.org/en/master/objects.inv ...
loading intersphinx inventory 'MyST parser docs' from https://myst-parser.readthedocs.io/en/latest/objects.inv ...
[1/2] Loading JSON schema: apidoc/json/index_transform_schema.yml
[2/2] Loading JSON schema: apidoc/json/inheritance_schema.yml
Parsed C++ input in 0.01181 seconds
Found 19 C++ declarations
myst v4.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'attrs_inline', 'deflist', 'smartquotes', 'replacements', 'substitution', 'strikethrough', 'fieldlist', 'tasklist', 'attrs_block'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={role: ...}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=True, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 49 source files that are out of date
updating environment: [new config] 49 added, 0 changed, 0 removed
reading sources... [100%] theme_result
C:\dev\sphinx-immaterial\docs\apidoc\cpp\apigen.rst.rst:107: WARNING: No Python entity named: 'tensorstore_demo.IndexDomain.__init__(json)'
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst.rst:166: WARNING: No top-level Python API group named: 'some-other-group', valid groups are: []
C:\dev\sphinx-immaterial\docs\apidoc\python\apigen.rst.rst:192: WARNING: No Python entity named: 'tensorstore_demo.IndexDomain.__init__(json)'
C:\dev\sphinx-immaterial\docs\python_apigen_demo.rst.rst:7: WARNING: No top-level Python API group named: 'indexing', valid groups are: []
C:\dev\sphinx-immaterial\docs\python_apigen_demo.rst.rst:12: WARNING: No top-level Python API group named: 'some-other-group', valid groups are: []
C:\dev\sphinx-immaterial\docs\python_apigen_demo.rst.rst:17: WARNING: No top-level Python API group named: 'type-param', valid groups are: []
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets...
copying static files...
Writing evaluated template result to C:\dev\sphinx-immaterial\docs\_build\html\_static\basic.css
Writing evaluated template result to C:\dev\sphinx-immaterial\docs\_build\html\_static\documentation_options.js
Writing evaluated template result to C:\dev\sphinx-immaterial\docs\_build\html\_static\language_data.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
C:\dev\sphinx-immaterial\.venv\Lib\site-packages\myst_parser\inventory.py:369: RemovedInSphinx10Warning: The iter() interface for _InventoryItem objects is deprecated. Please access the `project_name`, `project_version`, `uri`, and `displayname` attributes directly.
  project, version, loc, text = data[target]
writing output... [100%] theme_result
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:149: WARNING: py:class reference target not found: tensorstore_demo.Dim [ref.class]
C:\dev\sphinx-immaterial\docs\apidoc\python\index.rst:307: WARNING: py:class reference target not found: tensorstore_demo.DimensionSelection [ref.class]
C:\dev\sphinx-immaterial\docs\demo_api.rst:181: WARNING: js:class reference target not found: string [ref.class]
C:\dev\sphinx-immaterial\docs\demo_api.rst:186: WARNING: js:class reference target not found: SomeError [ref.class]
C:\dev\sphinx-immaterial\docs\graphviz.rst:94: WARNING: py:obj reference target not found: tensorstore_demo.DimensionSelection [ref.obj]
generating indices... genindex py-modindex done
highlighting module code... [100%] test_py_module.test
writing additional pages... done
copying images... [100%] rst-cheatsheet/sharealike.png
dumping search index in English (code: en)... done
dumping object inventory... done
Generating sitemap for 58 pages in C:\dev\sphinx-immaterial\docs\_build\html/sitemap.xml
build succeeded, 11 warnings.

[AA-Turner]

@2bndy5 I've just released Sphinx 9.0.0. #477 contains some suggested changes to improve compat.

A

[2bndy5]

The auto doc parts are really more of Jeremy's bag of tricks. But thanks for the lead!

[2bndy5]

I just ran our tests for sphinx v9 with patch from #477 and an updated uv.lock... There's additional problems beyond autodoc API. These warnings are elevated as errors in our tests:

• RemovedInSphinx11Warning: 'sphinx.environment.BuildEnvironment.app' is deprecated. Check CHANGES for Sphinx API modifications.

  • sphinx_immaterial/apidoc/python/apigen.py:606
  • sphinxcontrib/serializinghtml/__init__.py:100 @AA-Turner issues are disabled for sphinx-doc/sphinxcontrib-serializinghtml repo
  • sphinx_immaterial/apidoc/json/domain.py:667
  • sphinx_immaterial/apidoc/json/domain.py:803
  • sphinx_immaterial/apidoc/json/domain.py:757
  • sphinx_immaterial/apidoc/json/domain.py:950
  • sphinx_immaterial/inline_icons.py:71
  • sphinx_immaterial/graphviz.py:281
  • sphinx_immaterial/graphviz.py:241
  • sphinx_immaterial/apidoc/python/parameter_objects.py:650
  • sphinx_immaterial/apidoc/python/type_annotation_transforms.py:363
  • sphinx_immaterial/apidoc/python/type_annotation_transforms.py:221
  • sphinx_immaterial/apidoc/cpp/cpp_resolve_c_xrefs.py:83
  • sphinx_immaterial/apidoc/cpp/parameter_objects.py:527
  • sphinx_immaterial/apidoc/object_description_options.py:169
  • sphinx_immaterial/apidoc/cpp/apigen.py:181
  • sphinx_immaterial/apidoc/cpp/apigen.py:147
  • sphinx_immaterial/apidoc/cpp/apigen.py:143
  • sphinx_immaterial/search_adapt.py:144
  • sphinx_immaterial/nav_adapt.py:400
  • sphinx_immaterial/__init__.py:191

• RemovedInSphinx11Warning: 'tags' will become a required keyword argument for global_toctree_for_doc() in Sphinx 11.0.

  • tests/python_synopsis_test.py:23
  • tests/python_object_ids_test.py:43
  • tests/python_object_ids_test.py:20
  • tests/format_signatures_test.py:97
  • tests/cpp_domain_test.py:12