Sphinx autodoc 在本地工作,但在Read The Docs上不起作用。

huangapple go评论62阅读模式
英文:

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

huangapple
  • 本文由 发表于 2023年6月16日 06:17:37
  • 转载请务必保留本文链接:https://go.coder-hub.com/76485839.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定