Sphinx automodule本地正常ReadTheDocs失效及Python3.10配置错误求助

本地Sphinx #

ReadTheDocs #

本地Sphinx中EstraClient能正常显示，但ReadTheDocs的截图里该内容缺失，automodule指令未生效，完整代码可查看我的GitHub仓库。

用于EstraClient的reStructuredText代码：

EstraClient
============

.. automodule:: Estrapy
   :members:
   :undoc-members:
   :show-inheritance:

conf.py中已添加模块路径配置：

import os
import sys

sys.path.insert(0, os.path.abspath("../"))

更新1 #

升级至Python 3.10后，出现sphinx.errors.ConfigError错误，提示配置目录中不存在conf.py文件，完整错误输出：

Running Sphinx v5.3.0

Traceback (most recent call last):
  File "/home/docs/.asdf/installs/python/3.10.8/lib/python3.10/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/docs/.asdf/installs/python/3.10.8/lib/python3.10/site-packages/sphinx/application.py", line 202, in __init__
    self.config = Config.read(self.confdir, confoverrides or {}, self.tags)
  File "/home/docs/.asdf/installs/python/3.10.8/lib/python3.10/site-packages/sphinx/config.py", line 170, in read
    raise ConfigError(__("config directory doesn't contain a conf.py file (%s)") %
sphinx.errors.ConfigError: config directory doesn't contain a conf.py file (/home/docs/checkouts/readthedocs.org/user_builds/estrapy-api/checkouts/latest)

Configuration error:
config directory doesn't contain a conf.py file (/home/docs/checkouts/readthedocs.org/user_builds/estrapy-api/checkouts/latest)

我的.readthedocs.yaml代码：

version: 2
sphinx:
  configuration: docs/conf.py
  builder: html

build:
  os: ubuntu-20.04
  tools:
    python: "3.10"
  commands:
    - pip install myst-parser
    - pip install sphinx-rtd-theme
    - python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

解决方案 #

1. 修复conf.py找不到的问题

你的.readthedocs.yaml中自定义了构建命令，但最后一条sphinx命令指定的源码目录是当前目录（.），而conf.py实际在docs/目录下。可通过以下两种方式修改：

• 修改源码目录为docs/：

  # 替换build.commands最后一行
  - python -m sphinx -T -E -b html -d _build/doctrees -D language=en docs/ _build/html
  

• 或保持源码目录为.，显式指定配置文件路径：

  # 替换build.commands最后一行
  - python -m sphinx -T -E -b html -d _build/doctrees -D language=en -c docs/ . _build/html
  

2. 修复automodule未生效的问题

• 安装依赖包：ReadTheDocs构建环境是干净的，需确保安装你的Estrapy包，在构建命令中添加：

  # 在build.commands中新增该行
  - pip install -e ..
  

  此命令会从项目根目录安装开发版Estrapy，确保Sphinx能找到该模块。
• 验证路径配置：conf.py中的路径配置是相对docs/目录的，若仍有问题，可添加调试代码确认：

  # 在conf.py中添加调试代码
  print("当前sys.path:", sys.path)
  print("Estrapy路径是否存在:", os.path.exists(os.path.abspath("../Estrapy")))
  

• 确认包结构：检查Estrapy目录下是否有__init__.py文件，确保它是合法Python包，且EstraClient类在可导入路径下。

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