Mkdocs读取site-packages源码而非项目目录的问题求助

• 调整Python模块查找路径
  在docs目录下的配置文件（如conf.py，若使用mkdocstrings插件）中添加代码，将项目根目录插入到Python路径的最前端，确保优先加载本地代码：

  import sys
  from pathlib import Path
  
  # 将项目根目录添加到Python路径首位
  sys.path.insert(0, str(Path(__file__).parent.parent))
  

• 卸载本地已安装的项目包
  如果之前通过pip install .将项目安装到了site-packages，先执行卸载命令避免冲突：

  pip uninstall your-project-name
  

  替换your-project-name为你的实际项目名称。

• 使用虚拟环境隔离依赖
  创建并激活专属虚拟环境，仅安装MkDocs及所需插件，不安装本地项目：

  # 创建虚拟环境
  python -m venv venv
  
  # Windows激活
  venv\Scripts\activate
  
  # Linux/macOS激活
  source venv/bin/activate
  
  # 安装依赖
  pip install mkdocs mkdocstrings[python]
  

• 配置mkdocstrings插件路径（若使用）
  若用mkdocstrings生成API文档，在mkdocs.yml中明确指定模块查找路径为项目根目录：

  plugins:
    - mkdocstrings:
        default_handler: python
        handlers:
          python:
            options:
              paths: [.]
  

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