英文:
Sphinx autodoc works locally but not on Read The Docs
问题
我有一个GitHub仓库(链接在此),它非常基础,只是用来复现我在另一个仓库中遇到的问题(CPU Health Checks也在我的公共仓库中)。
它包含一个名为rtdtest的包,在本地是一个包含一个空的__init__.py
文件的rtdtest/文件夹。这个文件有两个简单的模块cpu_health.py和utilities.py,其中cpu_health.py使用以下语句导入utilities.py:
import rtdtest.utilities as utilities
在这种情况下,制作一个包并不是那么必要,但在我的“真实”仓库中,我需要它来访问项目根文件夹中子文件夹中的模块。
我的问题是,尽管我可以在本地使用Sphinx生成我想要的文档,其中包括使用automodule
语句在index.rst中创建的DocString生成的文档,但在创建Read The Docs文档时,构建通过了但带有警告消息:
警告:autodoc: 无法从模块'rtdtest'中导入模块'cpu_health';引发了以下异常:找不到模块'rtdtest' 警告:autodoc: 无法从模块'rtdtest'中导入模块'utilities';引发了以下异常:找不到模块'rtdtest'
说这个包的模块没有被导入,并建议我RTD没有将rtdtest识别为包而是模块(尽管我可能是错误的)。
在本地,使用以下行找到了该包:
sys.path.insert(0, os.path.abspath('../..'))
在conf.py文件中(conf.py位于项目根文件夹的docs/sphinx/中,比根文件夹前进了2个文件夹)。
我的(简化的)配置文件requirements.txt、.readthedocs.yml、setup.py、docs/sphinx/conf.py和docs/sphinx/requirements.txt都包含在GitHub仓库中(不能提供具体链接,因为stackoverflow将消息标记为垃圾邮件)。
我的主要文档文件是:index.rst
在我的仓库的管理高级设置部分,我已经选中了“Install Project”框以使用setup.py install将项目安装到virtualenv中,但我没有选中其他选项。文档类型我选择了“Sphinx HTML”。
我尝试多次编辑我的conf.py文件,以使用sys.path.insert添加文件夹到路径中,但当前文件夹和父文件夹的任何组合都不起作用。
我还尝试复制此前的帖子中提出的解决方案,他显然遇到了非常相似的问题并且能够解决,但即使尝试模仿他们的配置文件也没有起作用。
有人知道可能是什么问题吗?如果这在RTD文档中明确说明,我提前道歉,但这是我第一次使用这个工具,我找不到解决方法。
请让我知道是否需要提供其他信息以帮助解决问题。
谢谢!
Felipe
英文:
I have a GitHub repo (here) which is extremely basic and only meant to reproduce a problem I had with another repo (CPU Health Checks also in my public repos)
It consists on a package called rtdtest which locally is a rtdtest/ folder with an empty __init__.py
. This file has two simple modules cpu_health.py and utilities.py where cpu_health.py imports utilities.py with the statement
import rtdtest.utilities as utilities
In this case making a package is not that necessary but in my "real" repo I need it to access modules in subfolders within the proyect's root folder
My problem is that even though I am able to produce the documentation I want locally with sphinx which includes DocString generated documentation created with automodule
statements in index.rst, when creating the documentation in Read The Docs the build passes but with warning messages
> WARNING: autodoc: failed to import module 'cpu_health' from module
> 'rtdtest'; the following exception was raised: No module named
> 'rtdtest' WARNING: autodoc: failed to import module 'utilities' from
> module 'rtdtest'; the following exception was raised: No module named
> 'rtdtest'
Saying the modules from the package were not imported and suggesting to me that RTD is not recognizing rtdtest as a package but as a module (although I could be wrong there)
Locally the package is found with the line
sys.path.insert(0, os.path.abspath('../..'))
In file conf.py (conf.py is 2 folders ahead of the root folder of the project in docs/sphinx/)
My (minimalistic) configuration files requirements.txt, .readthedocs.yml, setup.py, docs/sphinx/conf.py, and docs/sphinx/requirements.txt are included in the GitHub repo (couldn't put specific links because stackoverflow called the message spam)
And my main documentation file is:
index.rst
In the admin Advance Settings section of my repo I have checked the "Install Project" box to "Install your project inside a virtualenv using setup.py install" but I haven't checked other one. For documentation type I chose "Sphinx HTML"
I tried multiple times to edit my conf.py file to add folders to the path using sys.path.insert but no combination of current and parent folders worked.
I also tried replicating the solution proposed in this previous post who apparently had a very similar problem and was able to solve it, but even trying to mimic their configuration files didn't work
Does anyone now what might be the problem? I am sorry in advance if this is clearly stated in the RTD documentation but this is my first time using the tool and I couldn't find a solution there
Please let me know if there is any additional information I should provide to help solving the problem
Cheers and thanks
Felipe
答案1
得分: 1
问题得以解决,感谢 @sinoroc 的建议和在这个 打包教程 中提供的项目结构建议。项目的结构导致了问题,因为我在项目的根目录和 setup.py 中都有 __init__.py 文件。
显然,这也导致了在某些计算机上安装包时出现问题,因此修复它非常重要。
我只需在包的根目录内创建了一个 /src/rtdtest 文件夹,并将 .py 文件移动到那里。然后,我更新了模块的导入语句和 .rst 文件中的新包名称,还在 setup.py 中添加了 "packages=find_packages('src')" 和 "package_dir={'':'src'}" 这两行,并修改了 .readthedocs.yml 文件以包含:
python:
version: 3.8
install:
- method: pip
path: .
extra_requirements:
- rtdtest
现在,ReadTheDocs 中的构建正常工作,按预期从模块的 DocStrings 创建文档。
英文:
The problem was solved thanks to @sinoroc suggestion and the project structure suggested presented in this packaging tutorial. The structure of the project was causing problems because I had the __init__.py file in the root of the project along with setup.py.
Apparently that also produced problems for installing the package in some computers so it was extremely important to fix it.
I just created a /src/rtdtest folder within the root of the package and shifted the .py files there. Then I updated the new package name in the module's import statement and .rst files, I also added lines "packages=find_packages('src')" and "package_dir={'':'src'}" to setup.py, and modified the .readthedocs.yml file to contain:
python:
version: 3.8
install:
- method: pip
path: .
extra_requirements:
- rtdtest
Now the build in ReadTheDocs worked fine, creating documentation from the module's DocStrings as expected
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论