狮身人面像 autodoc 没有导入任何东西？答案

【问题标题】：Sphinx autodoc not importing anything?狮身人面像 autodoc 没有导入任何东西？
【发布时间】：2014-07-23 08:23:55
【问题描述】：

我正在尝试使用sphinx（与autodoc 和numpydoc 一起）来记录我的模块，但在基本设置之后，运行make html 只生成基本的html，不包含文档字符串中的任何内容.我运行的是Python 3.3，项目结构大纲如下：

Kineticlib
|--docs
|  |--build
|  |--source
|  |  |--conf.py
|--src
|  |--kineticmulti
|  |  |--__init__.py
|  |  |--file1.py
|  |  |--file2.py
|--setup.py

__init__.py 为空，在conf.py 的docs/source 目录中我添加了sys.path.insert(0, os.path.abspath('../..'))

在docs 目录中运行make html 会得到以下输出：

sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.2.2
loading pickled environment... done
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.

Build finished. The HTML pages are in build/html.

那么，我做错了什么？

【问题讨论】：

标签： python python-sphinx autodoc numpydoc

【解决方案1】：

您是否在 docs/source 目录中运行 sphinx-apidoc？这将生成用于制作 html 的 .rst 文件。来自man sphinx-apidoc，

sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames ...]

您需要包含（至少）outputdir（.rst 文件所在的位置，./ 应该可以工作）和应该指向您的包的 sourcedir（看起来像 ../. ./src/kineticmulti 应该可以工作）

【讨论】：

是的，我忘了。

【解决方案2】：

正如人们所说，你应该这样做：

sphinx-apidoc [options] -o <outputdir> <sourcedir> [pathnames ...]

有时还需要修改 conf.py 以导入一些源模块。以及向类添加一些文档以加载其方法文档（仅适用于私有类，但我一直坚持这一点）。

【讨论】：