使用Sphinx构建文档时遭遇Docutils AttributeError问题求助

报错信息 #

File "/home/user/anaconda3/envs/doc/lib/python3.8/site-packages/docutils/parsers/rst/states.py", line 2933, in eof
    if self.memo.section_bubble_up_kludge:
AttributeError: 'Struct' object has no attribute 'section_bubble_up_kludge'

环境信息 #

Python 3.8.19

Package                       Version
----------------------------- ---------
alabaster                     0.7.13
Babel                         2.15.0
certifi                       2024.7.4
charset-normalizer            3.3.2
colorama                      0.4.6
commonmark                    0.9.1
docutils                      0.18.1
idna                          3.7
imagesize                     1.4.1
importlib_metadata            8.0.0
Jinja2                        3.1.4
livereload                    2.7.0
markdown-it-py                3.0.0
MarkupSafe                    2.1.5
mdit-py-plugins               0.4.1
mdurl                         0.1.2
myst-parser                   3.0.1
numpy                         1.24.4
packaging                     24.1
pillow                        10.4.0
pip                           24.0
Pygments                      2.18.0
pytz                          2024.1
PyYAML                        6.0.1
recommonmark                  0.7.1
requests                      2.32.3
setuptools                    69.5.1
snowballstemmer               2.2.0
Sphinx                        6.1.3
sphinx-autobuild              2021.3.14
sphinx-rtd-theme              2.0.0
sphinxcontrib-applehelp       1.0.4
sphinxcontrib-devhelp         1.0.2
sphinxcontrib-htmlhelp        2.0.1
sphinxcontrib-jquery          4.1
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.3
sphinxcontrib-serializinghtml 1.1.5
tornado                       6.4.1
tqdm                          4.66.4
urllib3                       2.2.2
wheel                         0.43.0
zipp                          3.19.2

已尝试方案 #

• 重新安装虚拟环境，问题未解决
• 尝试降级docutils版本，无效

解决方案 #

1. 调整myst-parser版本 #

当前使用的myst-parser 3.0.1对Sphinx版本要求较高，与你的Sphinx 6.1.3存在兼容性冲突。建议降级到适配Sphinx 6.x的版本：

pip install myst-parser==2.0.0

2. 匹配docutils与Sphinx的版本组合 #

Sphinx 6.1.3推荐搭配docutils 0.19.1，执行以下命令更新版本：

pip install docutils==0.19.1

3. 移除冲突的recommonmark #

recommonmark与myst-parser功能重叠，易导致解析逻辑冲突，建议卸载：

pip uninstall -y recommonmark

完成以上操作后，重新执行make html即可正常构建文档。

内容的提问来源于stack exchange，提问作者Mobius8086