[英]Sphinx cannot find my python files. Says 'no module named ...'
I have a question regarding the Sphinx autodoc generation.我有一个关于 Sphinx autodoc generation 的问题。 I feel that what I am trying to do should be very simple, but for some reason, it won't work.我觉得我想做的事情应该很简单,但由于某种原因,它行不通。
I have a Python project of which the directory is named slotting_tool .我有一个 Python 项目,其目录名为slotting_tool 。 This directory is located at C:\Users\Sam\Desktop\picnic-data-shared-tools\standalone\slotting_tool
此目录位于C:\Users\Sam\Desktop\picnic-data-shared-tools\standalone\slotting_tool
I set up Sphinx using sphinx-quickstart
.我使用sphinx-quickstart
设置了 Sphinx。 Then my directory structure (simplified) is as follows:那么我的目录结构(简化)如下:
slotting_tool/
|_ build/
|_ source/
|___ conf.py
|___ index.rst
|_ main/
|___ run_me.py
Now, I set the root directory of my project to slotting_tool
by adding the following to the conf.py
file.现在,我通过将以下内容添加到slotting_tool
文件来将项目的根目录设置为conf.py
。
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
Next, I update my index.rst
file to look like this:接下来,我index.rst
文件更新为如下所示:
.. toctree::
:maxdepth: 2
:caption: Contents:
.. automodule:: main.run_me
:members:
When trying to build my html using the sphinx-build -b html source.\build
command, I get the following output, with the no module named
error:当尝试使用sphinx-build -b html source.\build
命令构建我的 html 时,我得到以下 output, no module named
:
(base) C:\Users\Sam\Desktop\picnic-data-shared-tools\standalone\slotting_tool>sphinx-build -b html source .\build
Running Sphinx v1.8.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [] 0 added, 1 changed, 0 removed
reading sources... [100%] index
WARNING: autodoc: failed to import module 'run_me' from module 'main'; the following exception was raised:
No module named 'standalone'
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in build.
There are no HTML pages that refer to run_me.py
in build.在构建中没有引用run_me.py
的 HTML 页。 I have tried setting my root directory to all different kinds of directories and I have tried replacing all dots .
我已经尝试将我的根目录设置为所有不同类型的目录,并且我已经尝试替换所有的点.
with backslashes \
and so forth, but can't seem to find out what I'm doing wrong.带有反斜杠\
等等,但似乎无法找出我做错了什么。
By the way, the statement that standalone
is not a module is in fact true, it is just a directory without an __init__.py
.顺便说一句, standalone
不是模块的说法实际上是正确的,它只是一个没有__init__.py
的目录。 Don't know if that might have caused some trouble?不知道这样会不会造成什么麻烦?
Anyone have an idea?有人有想法吗?
This is the usual "canonical approach" to "getting started" applied to the case when your source code resides in a src
directory like Project/src
instead of simply being inside the Project
base directory.这是“入门”的常用“规范方法”,适用于源代码位于src
目录(如Project/src
而不是简单地位于Project
基目录中的情况。
Follows these steps:遵循以下步骤:
Create a docs
directory in your Project
directory (it's from this docs
directory the commands in the following steps are executed).在您的Project
目录中创建一个docs
目录(它是从这个docs
目录执行以下步骤中的命令)。
sphinx-quickstart
(choose separate source
from build
. Places .html
and .rst
files in different folders). sphinx-quickstart
(从build
选择单独的source
。将.html
和.rst
文件放在不同的文件夹中)。
sphinx-apidoc -o ./source ../src
make html
This would yield the following structure (provided you .py
source files reside in Project/src
):这将产生以下结构(假设.py
源文件驻留在Project/src
):
Project
|
├───docs
│ │ make.bat
│ │ Makefile
│ │
│ ├───build
│ └───source
│ │ conf.py
│ │ index.rst
│ │ modules.rst
│ │ stack.rst
│ │
│ ├───_static
│ └───_templates
└───src
stack.py
In your conf.py
you'd add (after step 2):在您的conf.py
添加(在第 2 步之后):
import os
import sys
sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'src')))
Also include in conf.py
:还包括在conf.py
:
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
And in index.rst
you'd link modules.rst
:在index.rst
您将链接modules.rst
:
Welcome to Project's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Your stack.rst
and modules.rst
were auto-generated by sphinx-apidoc
, no need to change them (at this point).您的stack.rst
和modules.rst
是由sphinx-apidoc
自动生成的,无需更改它们(此时)。 But just so you know this is what they look like:但只是为了让您知道这就是它们的样子:
stack.rst
: stack.rst
:
stack module
============
.. automodule:: stack
:members:
:undoc-members:
:show-inheritance:
modules.rst
: modules.rst
:
src
===
.. toctree::
:maxdepth: 4
stack
and:和:
sys.path.insert(0, os.path.abspath('../..'))
That's not correct.那不正确。 Steve Piercy's comment is not entirely on point (you don't need to add a __init__.py
since you're using a simple module) but they're right that autodoc will try to import the module and then inspect the content. Steve Piercy 的评论并不完全正确(您不需要添加__init__.py
因为您使用的是一个简单的模块)但他们是对的,autodoc 将尝试导入模块然后检查内容。
Hoever assuming your tree is假设你的树是
doc/conf.py
src/stack.py
then you're just adding the folder which contains your repository to the sys.path which is completely useless.那么您只是将包含您的存储库的文件夹添加到完全无用的 sys.path 中。 What you need to do is add the src
folder to sys.path, such that when sphinx tries to import stack
it finds your module.您需要做的是将src
文件夹添加到 sys.path,这样当 sphinx 尝试导入stack
它会找到您的模块。 So your line should be:所以你的线路应该是:
sys.path.insert(0, os.path.abspath('../src')
(the path should be relative to conf.py). (路径应该相对于 conf.py)。
Of note: since you have something which is completely synthetic and should contain no secrets, an accessible repository or a zip file of the entire thing makes it much easier to diagnose issues and provide relevant help: the less has to be inferred, the less can be wrong in the answer.值得注意的是:由于您拥有完全合成且不应包含任何秘密的内容,因此可访问的存储库或整个内容的 zip 文件可以更轻松地诊断问题并提供相关帮助:推断的越少,可以推断的越少答案是错误的。
Let's take an example with a project: dl4sci-school-2020
on master branch , commit: 6cbcc2c72d5dc74d2defa56bf63706fd628d9892 :让我们以一个项目为例: dl4sci-school-2020
在 master 分支上,提交:6cbcc2c72d5dc74d2defa56bf63706fd628d9892 :
├── dl4sci-school-2020
│ ├── LICENSE
│ ├── README.md
│ ├── src
│ │ └── __init__.py
│ └── utility
│ ├── __init__.py
│ └── utils.py
and utility package has a utils.py module :和实用程序包有一个 utils.py 模块:
Follow this process (FYI, I'm using sphinx-build 3.1.2 ):按照这个过程(仅供参考,我正在使用sphinx-build 3.1.2 ):
docs/
directory under you project:在您的项目下创建一个docs/
目录:mkdir docs
cd docs
docs/
, and just pass your project_name
, your_name
& version
of your choice and rest keep defaults.在docs/
启动 sphinx,然后传递您的project_name
、 your_name
和您选择的version
,其余保持默认值。sphinx-quickstart
you will get below auto-generated in your docs/
folder您将在docs/
文件夹中获得以下自动生成的信息
├── docs
│ ├── Makefile
│ ├── build
│ ├── make.bat
│ └── source
│ ├── _static
│ ├── _templates
│ ├── conf.py
│ └── index.rst
Since, we created a separate docs
directory so we need sphinx find where to find build files and python src module.因为,我们创建了一个单独的docs
目录,所以我们需要 sphinx 找到在哪里可以找到构建文件和 python src 模块。 So, edit the conf.py file, you can use my conf.py file too所以,编辑 conf.py 文件,你也可以使用我的 conf.py 文件
import os
import sys
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
sys.path.insert(0, basedir)
Now, to enable access to nested multiple packages & modules if any, you need to edit index.rst
file.现在,要启用对嵌套的多个包和模块的访问(如果有),您需要编辑index.rst
文件。
.. toctree::
:maxdepth: 2
:caption: Description of my CodeBase:
modules
The modules
picks up content from modules.rst
file which we will create below: Make sure you're still in doc/
to run the below command modules
从我们将在下面创建的modules.rst
文件中获取内容:确保您仍在doc/
中运行以下命令
sphinx-apidoc -o ./source ..
The output you get:你得到的输出:
├── docs
│ ├── Makefile
│ ├── build
│ ├── make.bat
│ └── source
│ ├── _static
│ ├── _templates
│ ├── conf.py
│ ├── index.rst
│ ├── modules.rst
│ ├── src.rst
│ └── utility.rst
now run:现在运行:
make html
Now, go and open in browser of your choice,现在,在您选择的浏览器中打开,
file:///<absolute_path_to_your_project>/dl4sci-school-2020/docs/build/html/index.html
have you beautiful documentation ready你准备好漂亮的文档了吗
https://imgur.com/5t1uguh https://imgur.com/5t1uguh
FYI, You can switch any theme of your choice, I found sphinx_rtd_theme
and extension sphinxcontrib.napoleon
super dope!.仅供参考,您可以切换您选择的任何主题,我找到了sphinx_rtd_theme
和扩展sphinxcontrib.napoleon
超级涂料!。 Thanks to their creators, so I used it.感谢他们的创造者,所以我使用了它。
below does the work!下面的工作!
pip install sphinxcontrib-napoleon
pip install sphinx-rtd-theme
You can host your documentation it on readthedocs enjoy documenting your code!您可以在readthedocs上托管您的文档,享受记录您的代码的乐趣!
对我来说,通过setup.py
文件安装包并重新运行相应的命令解决了这个问题:
$ python setup.py install
IMHO running pip install --no-deps -e.
恕我直言,运行pip install --no-deps -e.
in the top project folder (or where ever setup.py
is) to get an "editable" install is a better alternative to get your package modules on the PYTHONPATH
than altering it in docs/conf.py
using sys.path
.在顶级项目文件夹(或setup.py
所在的位置)中获得“可编辑”安装是在PYTHONPATH
上获取 package 模块的更好选择,而不是使用sys.path
在docs/conf.py
中更改它。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.