Sphinx 的 autodoc 的 automodule 显然没有效果

Question

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

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

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

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

I 运行 sphinx with sphinx-build -b html apidoc apidoc/_build 项目目录作为当前工作目录。

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

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

它运行没有错误，但是当我打开生成的 HTML 文件时，它只显示 "agent module" 并且一切都是空白的。为什么不显示 class Agent 及其成员？

更新：原来的问题可能是我没有把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

我会尝试通过将 "canonical" 方法与您的案例并排进行回答。

通常的"getting started approach"遵循以下步骤：

在你的project目录中创建一个doc目录（就是从这个目录执行以下步骤中的命令）。
sphinx-quickstart（从build中选择source）。
sphinx-apidoc -o ./source ..
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 你会 link 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('.'))

您的错误堆栈跟踪显示找不到模块 agent。这可能是因为你没有在你的 conf.py 中下降 1 级（它指向 .rst 的路径，而不是 .py 的路径），这应该有效： sys.path.insert(0, os.path.abspath('..'))。此外，如果您没有在 index.rst 中手动 edit/connect 您的 modules.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的位置。

另请注意，您提到："the project's directory as the current working directory." 我在 Whosebug 上的 sphinx 线程中看到 "working directory"，可互换地作为 Project 基本目录或 docs 目录。然而，如果你 search the Sphinx documentation for "working directory" 你会发现没有提到它。

最后，使用 "getting started approach" 的 file/directory 结构还有一个好处。它基本上 "puts you on the same page" 与 Sphinx 标签上的大多数线程，并且这种方式减轻了将案例映射到不同 directory/file 结构的脑力劳动。

希望对您有所帮助。

Sphinx 的 autodoc 的 automodule 显然没有效果

Sphinx's autodoc's automodule having apparently no effect

python

python-sphinx

autodoc

sphinx-apidoc