Python 斯芬克斯'；s autodoc'；s自动模块显然没有效果

我在包含

automodule

的

rst

文件上运行Sphinx，但它似乎没有任何效果

下面是详细信息：我有一个Python项目，其中有一个文件

agent.py

，其中包含一个类

agent

。我还有一个子目录

apidoc

，其中包含一个文件

agent.rst

（由

sphinx apidoc

生成）：

我使用

sphinx build-bhtml-apidoc-apidoc/\u build运行sphinx，将项目目录作为当前工作目录

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

导入操作系统
导入系统
sys.path.insert（0，os.path.abspath（'.'））

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

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

警告：automodule（'My Project.agent'）的签名无效
警告：不知道要导入哪个模块以自动记录“My Project.agent”（请尝试在文档中放置“module”或“currentmodule”指令，或给出明确的模块名称）
警告：autodoc:导入模块“代理”失败；引发了以下异常：
没有名为“代理”的模块

我将尝试通过将“规范”方法与您的案例并列来回答您的问题

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

在
项目
目录中创建一个
文档
目录（从该目录执行以下步骤中的命令）

sphinx快速启动
（从
build
中选择独立的
source
）

sphinx-apidoc-o./source..

生成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构建-b html-apidoc-apidoc/\u构建

在您的
conf.py
中：

sys.path.insert（0，os.path.abspath（'.'））



您的错误stacktrace表示找不到模块
代理
。这可能是因为您在
conf.py
中没有降低1级（它指向
.rst
的路径，而不是
.py
的路径），这应该可以工作：
sys.path.insert（0，os.path.abspath（'..'））
。此外，如果您没有在
index.rst
中手动编辑/连接您的
模块.rst
，您可能只会看到该模块。


您可能会注意到斯芬克斯命令的签名：

sphinx apidoc[选项]-o

sphinx构建[选项][文件名…]

指的是
.rst
所在的位置，而
指的是
.py
所在的位置<代码>
到放置
.rst
的位置，以及
到放置
.html
的位置

还请注意，您提到：“项目目录作为当前工作目录。”我在stackoverflow上的sphinx threads中看到过“工作目录”，可以互换为
项目
基本目录或
文档
目录。然而，如果你发现没有提到它

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

我希望这能有所帮助。
我将尝试通过将“规范”方法与您的案例并列来回答您的问题

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

在
项目
目录中创建一个
文档
目录（从该目录执行以下步骤中的命令）

sphinx快速启动
（从
build
中选择独立的
source
）

sphinx-apidoc-o./source..

生成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构建-b html-apidoc-apidoc/\u构建

在您的
conf.py
中：

sys.path.insert（0，os.path.abspath（'.'））



您的错误stacktrace表示找不到模块
代理
。这可能是因为您在
conf.py
中没有降低1级（它指向
.rst
的路径，而不是
.py
的路径），这应该可以工作：
sys.path.insert（0，os.path.abspath（'..'））
。此外，如果您没有在
index.rst
中手动编辑/连接您的
模块.rst
，您可能只会看到该模块。


您可能会注意到斯芬克斯命令的签名：

sphinx apidoc[选项]-o

sphinx构建[选项][文件名…]

指的是
.rst
所在的位置，而
指的是
.py
所在的位置<代码>

到哪里

.rst