狮身人面像的自动文档的自动模块显然没有效果

Question

我在一个包含automodule 的rst 文件上运行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 及其成员？

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

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. 在您的project 目录中创建一个doc 目录（在此目录中执行以下步骤中的命令）。

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

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('.'))

---

---

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

还请注意，您提到：“将项目目录作为当前工作目录。”我在 stackoverflow 上的 sphinx 线程中看到了“工作目录”，可以互换为 Project 基本目录或 docs 目录。但是，如果你 search the Sphinx documentation for "working directory" 你会发现没有提及它。

最后，使用“入门方法”的文件/目录结构有一个优势。它基本上与 Sphinx 标记上的大多数线程“将您放在同一页面上”，这样可以减轻将案例映射到不同目录/文件结构的脑力工作。

我希望这会有所帮助。