如何用MkDocs整合多Django包文档？mkdocstrings遇导入问题

你的思路完全没问题：用独立的docs仓库整合多包文档，通过开发模式安装依赖包，既不合并仓库，又能满足各个包独立发布的需求，是合理的方案。下面是针对性的排查和解决步骤：

1. 先验证模块是否真的可导入 #

在medux-docs的虚拟环境中，打开Python交互终端，执行：

import medux.core.middleware

如果报错，说明包的安装或结构有问题，而非mkdocs的问题：

• 检查pip list输出，确认medux等包是否以editable模式存在（显示为medux @ file:///xxx/medux），如果没有，重新执行pip install -e ../medux（确保当前在medux-docs目录，且../medux是正确的相对路径）。
• 检查medux包的结构：
  • 确认medux/core/middleware.py文件存在。
  • 检查包的配置文件（pyproject.toml/setup.py）：如果源码放在src目录下，必须在配置中指定源码根目录，比如pyproject.toml中添加：

    [tool.setuptools]
    package_dir = {"": "src"}
    packages = ["medux"]
    

  • 若使用Python 3.3+的隐式命名空间包，确保包根目录没有__init__.py（如果是传统结构则需要保留）。

2. 确保MkDocs使用正确的环境 #

有时候mkdocs会调用系统全局的Python解释器，而非当前虚拟环境的版本，导致找不到安装的包：

• 用python -m mkdocs serve替代直接执行mkdocs serve，强制使用当前虚拟环境的Python。
• 验证环境：执行which mkdocs，确认输出路径在当前虚拟环境的bin目录下。

3. 调整mkdocstrings配置 #

如果模块可正常导入但mkdocstrings仍找不到，可在mkdocs.yml中直接指定源码路径，跳过依赖安装的识别环节：

plugins:
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          paths:
            - ../medux
            - ../medux-common
            - ../medux-online

这个配置会让mkdocstrings直接从源码目录读取模块，无需依赖包的安装状态，适合开发场景。

4. 清除MkDocs缓存 #

缓存可能导致旧的模块路径残留，执行：

mkdocs serve --clean

或直接删除项目根目录下的.mkdocs_cache文件夹，再重新启动服务。

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