Sphinx的autodoc的automodule显然无效 [英] Sphinx's autodoc's automodule having apparently no effect
问题描述
我正在包含 automodule 的 rst 文件上运行Sphinx，但似乎没有任何效果。 / p>
以下是详细信息：我有一个Python项目，文件 agent.py 包含类 Agent 。我还有一个子目录 apidoc ，其中有文件 agent.rst （由 sphinx生成） -apidoc ）：
代理模块
========= ===
.. 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 而引起的。不过，既然这样做了，我会收到类似以下的警告：
警告：自动模块（'My Project.agent'）的签名无效
警告：不知道要导入哪个文件以自动记录'My Project.agent'（尝试在模块或 currentmodule指令中放置文档或提供明确的模块名称）
警告：autodoc：无法导入模块'agent'；引发了以下异常：
没有名为 agent的模块
我将尝试通过将规范方法与您的案例并列进行回答。
通常的入门方法遵循以下步骤：
-
创建
doc项目目录中的目录（从该目录中执行以下步骤中的命令）。 -
sphinx-quickstart（从build中选择单独的源）。 -
sphinx-apidoc -o ./source .. -
制作html
这将产生以下结构：
C：\项目
|
| agent.py
|
| --- docs
| | make.bat
| |生成文件
| |
| | ---建立
| |
| | ---源
| | 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 ：
欢迎使用Project的文档！
===============================
.. toctree ::
：最大深度：2
：标题：内容：
模块
指数和表格
====== =============
*：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 。那可能是因为您没有在 conf.py 中降低1级（它指向的是 .rst ，而不是 .py ）的路径，这应该可以工作：
sys.path.insert（0，os.path.abspath （'..'））。另外，如果您没有在 index.rst 中手动编辑/连接 modules.rst ，则可能只看到那个模块。
您可能会注意到正在播放的狮身人面像命令的签名： sphinx-apidoc [选项] -o< OUTPUT_PATH> < MODULE_PATH>
sphinx-build [选项]< sourcedir> < outputdir> [文件名...]
< sourcedir> 指 .rst 的位置，而< MODULE_PATH> 指的是 .py的位置是。 < OUTPUT_PATH> 放置到 .rst 和< outputdir> 放置到 .html 的位置。
还请注意，您提到：该项目的目录为当前工作目录。我已经在stackoverflow的sphinx线程中看到了工作目录，它既可以作为 Project 基本目录，也可以作为 docs 目录。但是，如果您在Sphinx文档中搜索工作目录 您不会发现它。
最后，使用入门方法的文件/目录结构是有好处的。基本上，Sphinx标记上的大多数线程都会将您置于同一页上，从而减轻了将案例映射到不同目录/文件结构的麻烦。
我希望这会有所帮助。
I am running Sphinx on a rst file containing automodule but it does not seem to have any effect.
Here are the details: I have a Python project with a file agent.py containing a class Agent in it. I also have a subdirectory apidoc with a file agent.rst in it (generated by sphinx-apidoc):
agent module
============
.. automodule:: agent
:members:
:undoc-members:
:show-inheritance:
I run sphinx with sphinx-build -b html apidoc apidoc/_build with the project's directory as the current working directory.
To make sure the Python files are found, I've included the following in apidoc/conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
It runs without errors but when I open the resulting HTML file it only shows "agent module" and everything is blank. Why isn't it showing the class Agent and its members?
Update: the original problem was likely caused by the fact that I had not included sphinx.ext.autodoc in conf.py. Now that I did, though, I get warnings like:
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'
解决方案 I'll try answering by putting the "canonical" approach side-by-side with your case.
The usual "getting started approach" follows these steps:
create a doc directory in your project directory (it's from this directory the commands in the following steps are executed).
sphinx-quickstart (choosing separate source from build).
sphinx-apidoc -o ./source ..
make html
This would yield the following structure:
C:\Project
|
| agent.py
|
|---docs
| | make.bat
| | Makefile
| |
| |---build
| |
| |---source
| | conf.py
| | agent.rst
| | index.rst
| | modules.rst
In your conf.py you'd add (after step 2):
sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
and in index.rst you'd link modules.rst:
Welcome to Project's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Now compare the above with what you have - from what you shared in your question:C:\Project
|
| agent.py
|
|---apidoc
| | agent.rst
| | conf.py
| |
| |-- _build
You ran:
sphinx-build -b html apidoc apidoc/_build
and in your conf.py:
sys.path.insert(0, os.path.abspath('.'))
Your error stacktrace says it couldn't find the module agent. That's probably because you didn't go 1 level down in your conf.py (it's pointing to the path with .rst, not the path with .py), this should work:
sys.path.insert(0, os.path.abspath('..')). Also, if you didn't manually edit/connect your modules.rst in your index.rst you are likely to only see that module.
You may care to notice the signatures of the sphinx commands at play:sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>
sphinx-build [options] <sourcedir> <outputdir> [filenames …]
<sourcedir> refers to where .rst are, and <MODULE_PATH> to where .py are. <OUTPUT_PATH> to where .rst are placed, and <outputdir> to where .html are placed.
Please also notice, you mentioned: "the project's directory as the current working directory." I've seen "working directory" mentioned in sphinx threads on stackoverflow, interchangeably as both the Project base directory, or the docs directory. However, if you search the Sphinx documentation for "working directory" you'll find no mention of it.
Finally, there is an advantage to using the file/directory structure of the "getting started approach". It basically "puts you on the same page" with most threads on the Sphinx tag, and that way alleviates the mental work of mapping the cases to different directory/file structures.
I hope this helps.
这篇关于Sphinx的autodoc的automodule显然无效的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
