search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.6k stars 2.12k forks source link

sphinx~=7.3.0 breaks sphinx-immaterial #12295

Closed JacobChesslo closed 7 months ago

JacobChesslo commented 7 months ago

Describe the bug

sphinx~=7.3.0 seems to break the sphinx-immaterial theme, whereas sphinx~=7.2.0 works fine with this theme

How to Reproduce

I'm using docker/compose to minimize the environment for testability (it's reproducible elsewhere, but wanting to keep this simple)

Files

docker-compose.yml:

services:
  docs:
    build:
      context: ./
      dockerfile: Dockerfile

Dockerfile:

FROM python:3.12
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
WORKDIR /docs
COPY ./requirements.txt /docs/requirements.txt
COPY ./src /docs/src
RUN pip install -r requirements.txt && pip freeze && sphinx-build -E -W --keep-going -q -n -T src _build/linkcheck
# Running with minimum flags `sphinx-build src _build` or `sphinx-build src -b linkcheck src _build/linkcheck` also breaks

requirements.txt:

sphinx~=7.3.0  # using ~=7.2.0 instead does not have this issue
sphinx-immaterial~=0.11

src/conf.py

root_doc = "index"
extensions = ["sphinx_immaterial"]
html_theme = "sphinx_immaterial"

src/index.rst

Some Example Docs
=================

Hello World

Steps

1) Running docker compose build results in the following pip freeze and traceback in the build logs:

alabaster==0.7.16
annotated-types==0.6.0
appdirs==1.4.4
Babel==2.14.0
certifi==2024.2.2
charset-normalizer==3.3.2
docutils==0.21.1
idna==3.7
imagesize==1.4.1
Jinja2==3.1.3
MarkupSafe==2.1.5
packaging==24.0
pydantic==2.7.0
pydantic-extra-types==2.6.0
pydantic_core==2.18.1
Pygments==2.17.2
requests==2.31.0
setuptools==69.2.0
snowballstemmer==2.2.0
Sphinx==7.3.4
sphinx_immaterial==0.11.11
sphinxcontrib-applehelp==1.0.8
sphinxcontrib-devhelp==1.0.6
sphinxcontrib-htmlhelp==2.0.5
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.7
sphinxcontrib-serializinghtml==1.1.10
typing_extensions==4.11.0
urllib3==2.2.1
wheel==0.43.0
Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/sphinx/registry.py", line 453, in load_extension
    mod = import_module(extname)
          ^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 995, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/usr/local/lib/python3.12/site-packages/sphinx_immaterial/apidoc/python/default.py", line 7, in <module>
    from . import parameter_objects
  File "/usr/local/lib/python3.12/site-packages/sphinx_immaterial/apidoc/python/parameter_objects.py", line 4, in <module>
    from sphinx.domains.python import PyTypedField
ImportError: cannot import name 'PyTypedField' from 'sphinx.domains.python' (/usr/local/lib/python3.12/site-packages/sphinx/domains/python/__init__.py)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/sphinx/cmd/build.py", line 332, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/sphinx/application.py", line 229, in __init__
    self.setup_extension(extension)
  File "/usr/local/lib/python3.12/site-packages/sphinx/application.py", line 402, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/local/lib/python3.12/site-packages/sphinx/registry.py", line 466, in load_extension
    metadata = setup(app)
               ^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/sphinx_immaterial/__init__.py", line 299, in setup
    app.setup_extension("sphinx_immaterial.apidoc.python.default")
  File "/usr/local/lib/python3.12/site-packages/sphinx/application.py", line 402, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/local/lib/python3.12/site-packages/sphinx/registry.py", line 456, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname,
sphinx.errors.ExtensionError: Could not import extension sphinx_immaterial.apidoc.python.default (exception: cannot import name 'PyTypedField' from 'sphinx.domains.python' (/usr/local/lib/python3.12/site-packages/sphinx/domains/python/__init__.py))

Extension error:
Could not import extension sphinx_immaterial.apidoc.python.default (exception: cannot import name 'PyTypedField' from 'sphinx.domains.python' (/usr/local/lib/python3.12/site-packages/sphinx/domains/python/__init__.py))

Environment Information

Platform:              linux; (Linux-4.18.0-536.el8.x86_64-x86_64-with-glibc2.36)
Python version:        3.12.3 (main, Apr 10 2024, 14:35:18) [GCC 12.2.0])
Python implementation: CPython
Sphinx version:        7.3.4
Docutils version:      0.21.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Sphinx extensions

["sphinx_immaterial"]

Additional context

No response

AA-Turner commented 7 months ago

Sphinx 7.3.5 has been released with fixes.

A

JacobChesslo commented 7 months ago

Just went through sphinx-immaterial's usage of sphinx.domains.python, looks like we missed a few reimports in 7.3.5: https://github.com/search?q=repo%3Ajbms%2Fsphinx-immaterial+sphinx.domains.python&type=code

Edit: looks like https://github.com/sphinx-doc/sphinx/pull/12297 may fully resolve this

yoctoyotta1024 commented 7 months ago

Sphinx 7.3.4. worked well for me but now I get the error:

Exception occurred:
  File "/Users/yoctoyotta1024/opt/anaconda3/envs/cienv/lib/python3.12/site-packages/breathe/directives/function.py", line 161, in DoxygenFunctionDirective
    def _parse_args(self, function_description: str) -> Optional[cpp.ASTParametersQualifiers]:
                                                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: module 'sphinx.domains.cpp' has no attribute 'ASTParametersQualifiers'

Please may you fix this? I guess you missed from C++ reimports as well as the Python ones (maybe other too?)

hobu commented 7 months ago

Chiming in to report this also breaks in the same way for Breathe as well.

AA-Turner commented 7 months ago

Sphinx 7.3.6 has been released.

A