Sphinx的autodoc的automodule显然无效

Question

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

详细信息如下：我有一个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及其成员？

更新
：原来的问题可能是由这样的事实，我没有引起包括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要html" target="_blank">添加的内容中（第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。这可能是因为你没有去1级记在你的conf.py（它的指向与路径.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放置。

还请注意，您提到：“该项目的目录为当前工作目录。”
我已经在的sphinx线程中看到了“工作目录”，可以同时作为Project基本目录或docs目录使用。但是，如果您在Sphinx文档中搜索“工作目录”，则不会提及它。

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

我希望这有帮助。