使用mkdocs serve时mkdocstrings-python-legacy触发AttributeError错误

问题场景 #

我使用mkdocs、mkdocs-same-dir、mkdocs-simple、mkdocstrings和mkdocstrings-python-legacy为一个小型包编写文档，执行mkdocs serve查看文档时触发以下属性错误：

AttributeError: module 'mkdocstrings_handlers.python' has no attribute 'get_handler'

我的mkdocs.yml配置 #

site_name: TOLIMAN
docs_dir: .
extra_css:
    - extra.css

plugins:
    - search
    - same-dir
    - simple
    - mkdocstrings:
        default_handler: python 
    - spellcheck

theme: 
    name: material 

当前依赖列表（poetry show --only=docs输出） #

certifi                    2022.12.7  Python package for providing Mozilla's CA Bundle.
charset-normalizer         3.0.1      The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet.
click                      8.1.3      Composable command line interface toolkit
codespell                  2.2.2      Codespell
colorama                   0.4.6      Cross-platform colored terminal text.
docstring-parser           0.15       Parse Python docstrings in reST, Google and Numpydoc format
editdistpy                 0.1.3      Fast Levenshtein and Damerau optimal string alignment algorithms.
ghp-import                 2.1.0      Copy your docs directly to the gh-pages branch.
idna                       3.4        Internationalized Domain Names in Applications (IDNA)
jinja2                     3.1.2      A very fast and expressive template engine.
markdown                   3.3.7      Python implementation of Markdown.
markupsafe                 2.1.2      Safely add untrusted strings to HTML/XML markup.
mergedeep                  1.3.4      A deep merge function for 🐍.
mkdocs                     1.4.2      Project documentation with Markdown.
mkdocs-autorefs            0.4.1      Automatically link across pages in MkDocs.
mkdocs-material            9.0.5      Documentation that simply works
mkdocs-material-extensions 1.1.1      Extension pack for Python Markdown and MkDocs Material.
mkdocs-same-dir            0.1.2      MkDocs plugin to allow placing mkdocs.yml in the same directory as documentation
mkdocs-simple-plugin       2.1.2      Plugin for adding simple wiki site creation from markdown files interspersed within your code with MkDocs.
mkdocs-spellcheck          1.0.0      A spell checker plugin for MkDocs.
mkdocstrings               0.19.1     Automatic documentation from sources, for MkDocs.
mkdocstrings-python-legacy 0.2.3      A legacy Python handler for mkdocstrings.
packaging                  23.0       Core utilities for Python packages
pygments                   2.14.0     Pygments is a syntax highlighting package written in Python.
pymdown-extensions         9.9.1      Extension pack for Python Markdown.
python-dateutil            2.8.2      Extensions to the standard Python datetime module
pytkdocs                   0.16.1     Load Python objects documentation.
pyyaml                     6.0        YAML parser and emitter for Python
pyyaml-env-tag             0.1        A custom YAML tag for referencing environment variables in YAML files. 
regex                      2022.10.31 Alternative regular expression module, to replace re.
requests                   2.28.2     Python HTTP for Humans.
six                        1.16.0     Python 2 and 3 compatibility utilities
symspellpy                 6.7.7      Python SymSpell
urllib3                    1.26.14    HTTP library with thread-safe connection pooling, file post, and more.
watchdog                   2.2.1      Filesystem events monitoring

解决方案 #

问题源于mkdocstrings配置与已安装的处理器不匹配：你装的是旧版的mkdocstrings-python-legacy处理器，但配置里指定default_handler: python时，mkdocstrings会尝试加载未安装的新版mkdocstrings_handlers.python模块，导致报错。

方案一（适配已安装的legacy处理器） #

修改mkdocs.yml中的mkdocstrings配置，明确指定使用legacy处理器：

plugins:
    - search
    - same-dir
    - simple
    - mkdocstrings:
        default_handler: python-legacy  # 将原"python"改为"python-legacy"
    - spellcheck

保存配置后重新执行mkdocs serve即可。

方案二（切换到新版Python处理器） #

如果你想使用新版处理器，先卸载旧版：

poetry remove mkdocstrings-python-legacy

然后安装新版：

poetry add --dev mkdocstrings[python]

保持原配置中default_handler: python不变即可，但注意新版处理器的文档引用语法可能与legacy版本有差异，需对应调整。

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