Sphinx 的 autodoc 的 automodule 显然没有效果

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：

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

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

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

更新：最初的问题很可能是由于我没有包含sphinx.ext.autodoc在conf.py. 但是，现在我这样做了，我收到了如下警告：

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

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 步之后）：

C:\Project
|
|   agent.py
|   
|---docs
|   |   make.bat
|   |   Makefile
|   |   
|   |---build
|   |               
|   |---source
|       |   conf.py
|       |   agent.rst
|       |   index.rst
|       |   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`

现在将以上内容与您所拥有的内容进行比较-来自您在问题中分享的内容：

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(os.path.join('..', '..')))

您的错误堆栈跟踪说它找不到模块agent。那可能是因为您没有在您的conf.py（它指向带有 的路径.rst，而不是带有 的路径.py）中降低 1 级，这应该有效： sys.path.insert(0, os.path.abspath('..'))。此外，如果您没有手动编辑/连接您的模块modules.rst，您index.rst可能只会看到该模块。 您可能会注意到正在运行的 sphinx 命令的签名：

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

<sourcedir>指在哪里.rst，<MODULE_PATH>在哪里.py。<OUTPUT_PATH>到.rst被放置，并<outputdir>以其中.html放置。

还请注意，您提到：“项目的目录作为当前工作目录。” 我在 stackoverflow 上的 sphinx 线程中看到了“工作目录”，可以互换地作为Project基本目录或docs目录。但是，如果您在 Sphinx 文档中搜索“工作目录”，您将找不到任何提及。

最后，使用“入门方法”的文件/目录结构有一个优势。它基本上与 Sphinx 标签上的大多数线程“使您处于同一页面上”，并且这种方式减轻了将案例映射到不同目录/文件结构的心理工作。

我希望这有帮助。