5

我在包含但似乎没有任何效果的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'
4

1 回答 1

9

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

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

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

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。这可能是因为你没有在你的中下降 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

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

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

我希望这有帮助。

于 2020-01-28T15:08:41.480 回答