Sphinx的autodoc的自动模块显然没有任何作用

Question

我正在包含rst的automodule文件上运行Sphinx，但似乎没有任何效果。

这里是详细信息：我有一个Python项目，其中的文件agent.py中包含类Agent。我还有一个子目录apidoc，其中有文件agent.rst（由sphinx-apidoc生成）：

agent module
============

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

我使用项目目录作为当前工作目录的sphinx-build -b html apidoc apidoc/_build运行sphinx。

为了确保找到Python文件，我在apidoc/conf.py中添加了以下内容：

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

它运行没有错误，但是当我打开生成的HTML文件时，它仅显示“代理模块”，并且所有内容均为空白。为什么不显示类Agent及其成员？

Update：原始问题可能是由于我没有在sphinx.ext.autodoc中包含conf.py而引起的。不过，既然我做到了，就会收到类似以下警告：

WARNING: invalid signature for automodule ('My Project.agent')
WARNING: don't know which module to import for autodocumenting 'My Project.agent' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: autodoc: failed to import module 'agent'; the following exception was raised:
No module named 'agent'

Answer 1

我将通过将“规范”方法与您的案例并列进行回答。

通常的“入门方法”遵循以下步骤：

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

2. sphinx-quickstart（从source中选择单独的build）。

3. sphinx-apidoc -o ./source ..

4. make html

这将产生以下结构：

C:\Project
|
|   agent.py
|   
|---docs
|   |   make.bat
|   |   Makefile
|   |   
|   |---build
|   |               
|   |---source
|       |   conf.py
|       |   agent.rst
|       |   index.rst
|       |   modules.rst

在conf.py中，您将添加（在第2步之后：

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

并且在index.rst中，您将链接modules.rst：

Welcome to Project's documentation!
================================

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

   modules


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

---

---

现在，将以上内容与您所分享的内容进行比较：

C:\Project
|
|   agent.py
|   
|---apidoc
|   |   agent.rst
|   |   conf.py
|   |
|   |-- _build

您跑了：sphinx-build -b html apidoc apidoc/_build

以及您的conf.py：

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

---

---

您的错误stacktrace指出找不到模块agent。那可能是因为您没有在conf.py中向下移动1级（它指向的是.rst的路径，而不是.py的路径），这应该可以工作：sys.path.insert(0, os.path.abspath('..'))。另外，如果您没有在modules.rst中手动编辑/连接index.rst，则可能只会看到该模块。

---

---

您可能会注意到在运行中sphinx命令的签名：

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>

sphinx-build [options] <sourcedir> <outputdir> [filenames …]

[<sourcedir>是指.rst的位置，<MODULE_PATH>是指.py的位置。将<OUTPUT_PATH>放置在.rst的位置，将<outputdir>放置在.html的位置。

[还请注意，您提到：“该项目的目录为当前工作目录。”我已经在stackoverflow的sphinx线程中看到了“工作目录”，它既可以作为Project基本目录，也可以作为docs目录互换。但是，如果您search the Sphinx documentation for "working directory"，您将一无所获。

最后，使用“入门方法”的文件/目录结构是有优势的。基本上，Sphinx标记上的大多数线程都会“将您置于同一页上”，从而减轻了将案例映射到不同目录/文件结构的工作量。

我希望这会有所帮助。