Sphinx找不到我的python文件。说“没有名为...的模块”

时间：2018-12-07 10:52:27

标签： python python-3.x python-sphinx autodoc

我对Sphinx自动文档生成有疑问。我觉得我想做的事情应该很简单，但是由于某种原因，它是行不通的。

我有一个Python项目，其目录名为 slotting_tool 。该目录位于C:\Users\Sam\Desktop\picnic-data-shared-tools\standalone\slotting_tool

我使用sphinx-quickstart设置了Sphinx。然后，我的目录结构（简化）如下：

slotting_tool/
|_ build/
|_ source/
|___ conf.py
|___ index.rst
|_ main/
|___ run_me.py

现在，通过将以下内容添加到slotting_tool文件中，将项目的根目录设置为conf.py。

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

接下来，我将我的index.rst文件更新为：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. automodule:: main.run_me
   :members:

尝试使用sphinx-build -b html source .\build命令构建html时，出现以下输出，并显示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.

在构建中没有引用run_me.py的HTML页面。我尝试将根目录设置为所有不同种类的目录，并尝试将所有点.替换为反斜杠\等，但似乎无法找出我在做什么。

顺便说一句，standalone不是模块的说法实际上是正确的，它只是一个没有__init__.py的目录。不知道这是否会造成一些麻烦？

有人有主意吗？

4 个答案:

答案 0 :(得分：6)

这是应用于的通常的“入门方法”，即您的源代码位于src之类的Project/src目录中，而不是仅仅位于{{ 1}}基本目录。

请遵循以下步骤：

  1. 在您的Project目录中创建一个docs目录（从该Project目录中执行以下步骤中的命令）。

  2. docs（从sphinx-quickstart中选择source。将build和.html文件放在不同的文件夹中）。

  3. .rst

  4. sphinx-apidoc -o ./source ../src

这将产生以下结构（前提是make html源文件位于.py中）

Project/src

您将在Project | ├───docs │ │ make.bat │ │ Makefile │ │ │ ├───build │ └───source │ │ conf.py │ │ index.rst │ │ modules.rst │ │ stack.rst │ │ │ ├───_static │ └───_templates └───src stack.py 中添加（在第2步之后）：

conf.py

还包括在import os import sys sys.path.insert(0, os.path.abspath(os.path.join('..', '..', 'src'))) 中：

conf.py

在extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']中，您将链接index.rst：

modules.rst

您的Welcome to Project's documentation! ================================ .. toctree:: :maxdepth: 2 :caption: Contents: modules Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` 和stack.rst由modules.rst自动生成，无需更改（此时）。只是让您知道这就是它们的样子：

sphinx-apidoc：

stack.rst

stack module ============ .. automodule:: stack :members: :undoc-members: :show-inheritance: ：

modules.rst
在使“ make html”在浏览器中打开“ Project / docs / build / index.html”后，结果：

enter image description here

和：

enter image description here

答案 1 :(得分：3)

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

那是不正确的。史蒂夫·皮尔西（Steve Piercy）的评论并不完全正确（因为您使用的是简单模块，因此无需添加__init__.py），但它们是对的，自动文档将尝试导入模块然后检查内容。

假设您的树是

doc/conf.py
src/stack.py

然后，您只是将包含存储库的文件夹添加到sys.path中，这是完全没有用的。您需要做的是将src文件夹添加到sys.path中，以便在sphinx尝试导入stack时找到您的模块。所以你的行应该是：

sys.path.insert(0, os.path.abspath('../src')

（路径应相对于conf.py）。

值得注意的是：由于您拥有完全合成的内容，不应包含任何秘密，因此整个内容的可访问存储库或zip文件使诊断问题和提供相关帮助变得更加容易：需要推断的内容更少，答案中的错误就越少。

答案 2 :(得分：1)

让我们以一个项目为例：dl4sci-school-2020 on master branch， 提交：6cbcc2c72d5dc74d2defa56bf63706fd628d9892 ：

├── dl4sci-school-2020
│   ├── LICENSE
│   ├── README.md
│   ├── src
│   │   └── __init__.py
│   └── utility
│       ├── __init__.py
│       └── utils.py

和utility package has a utils.py module：

遵循此过程（仅供参考，我正在使用 sphinx-build 3.1.2 ）：

  1. 在您的项目下创建一个docs/目录：
mkdir docs
cd docs
  1. 在docs/中启动狮身人面像，然后通过您选择的project_name，your_name和version，其余部分保留默认值。
sphinx-quickstart

您会在docs/文件夹中自动生成以下内容

├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       └── index.rst

自从我们创建了一个单独的docs目录以来，我们需要使用狮身人面像查找 在哪里找到构建文件和python src模块。 因此，编辑conf.py文件，您也可以使用我的conf.py文件

import os
import sys
basedir = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
sys.path.insert(0, basedir)

现在，要启用对嵌套的多个软件包和模块（如果有）的访问，您需要编辑index.rst文件。

.. toctree::
   :maxdepth: 2
   :caption: Description of my CodeBase:

   modules

modules从modules.rst文件中提取内容，我们将在下面创建该文件： 确保您仍在doc/中运行以下命令

sphinx-apidoc -o ./source ..

您得到的输出：

├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       ├── index.rst
│       ├── modules.rst
│       ├── src.rst
│       └── utility.rst

现在运行：

make html

现在，转到您选择的浏览器中打开

file:///<absolute_path_to_your_project>/dl4sci-school-2020/docs/build/html/index.html

您已经准备好漂亮的文档 auto-generated python docs.

https://imgur.com/5t1uguh

仅供参考，您可以切换任何选择的主题，我发现sphinx_rtd_theme和扩展名sphinxcontrib.napoleon超级涂料！感谢他们的创造者，所以我使用了它。

下面是工作！

pip install sphinxcontrib-napoleon
pip install sphinx-rtd-theme

您可以将文档托管在readthedocs上 喜欢编写代码！

答案 3 :(得分：0)

对我来说，通过 setup.py 文件安装软件包并重新运行相应的命令解决了问题：

$ python setup.py install
相关问题
最新问题