如何通过Sphinx与myst-parser将Markdown文档导入Readthedocs

• 1. 补全conf.py的必填配置
     很多时候本地Sphinx环境有默认配置容错，但RTD环境需要显式指定核心参数：
     给docs/source/conf.py添加以下配置：

  import sys
  from pathlib import Path
  # 把项目根目录加入Python导入路径，解决autodoc找不到模块的问题
  sys.path.insert(0, str(Path(__file__).parent.parent.parent.resolve()))
  
  # 显式指定根文档为index.md，Sphinx 4.0+用root_doc，旧版本用master_doc
  root_doc = "index"
  # 替换原有的source_suffix列表为字典格式，明确后缀对应的解析器，避免识别冲突
  source_suffix = {
      ".rst": "restructuredtext",
      ".md": "markdown"
  }
  

• 2. 检查index.md中的toctree语法是否符合myst规范
     要在Markdown文件中使用Sphinx的目录树功能，必须使用myst支持的fenced code block格式的toctree，且引用其他文档时不要加.md后缀，示例正确写法如下：

  # 项目文档首页
  
  这里是首页介绍内容
  
  ```{toctree}
  :maxdepth: 2
  :caption: 文档目录
  :hidden:
  
  快速开始 <quickstart>
  接口文档 <api/modules>
  常见问题 <faq>
  

  如果你之前用的是reStructuredText格式的toctree语法，或者加了.md后缀，都会导致目录识别失败，出现空白首页。
  

• 3. 核对RTD构建日志的警告信息
     虽然RTD提示构建成功，但如果出现toctree reference not found、Could not import module这类警告，也会导致页面缺失：
  • 如果出现模块导入失败的警告，确认你的setup.cfg/pyproject.toml中包配置正确，安装时能正确把你的项目代码放到Python环境的site-packages中
  • 如果出现文件找不到的警告，确认所有toctree中引用的文件路径和实际文件路径一致，路径相对于docs/source目录
• 4. 统一本地和RTD的依赖版本
     避免因依赖版本差异导致的解析异常，修改setup.cfg中的docs依赖，锁定兼容版本范围：

  [options.extras_require]
  docs =
      sphinx>=5.0.0,<7.0.0
      myst-parser>=1.0.0,<3.0.0
  

• 5. 本地复现RTD构建逻辑排查
     你之前是在docs/目录下执行make构建，而RTD是在项目根目录执行构建，路径上下文不同可能导致本地没问题但RTD出错，可以在本地执行以下命令复现RTD的构建逻辑：

  # 进入项目根目录，而非docs目录
  cd /path/to/your/project
  # 新建干净虚拟环境测试
  python -m venv test_rtd_env
  source test_rtd_env/bin/activate # Windows下执行 test_rtd_env\Scripts\activate
  # 安装文档依赖
  pip install -e ".[docs]"
  # 执行和RTD逻辑一致的构建命令
  sphinx-build docs/source docs/build/html
  

  执行后检查docs/build/html目录下的页面是否正常，即可复现RTD侧的问题，针对性修复。

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