Sphinx自动文档未导入任何内容？

Question

我正在尝试使用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是空的，在docs/source目录下的conf.py中，我添加了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.

那么，我做错了什么？

- George Oblapenko

Answer 1

你是否在 docs/source 目录下运行了 sphinx-apidoc 命令？该命令会生成用于生成 HTML 的 .rst 文件。参考 man sphinx-apidoc。

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

你需要至少包括outputdir（指定.rst文件的输出目录，"./"应该可以工作）和sourcedir参数，它应该指向你的程序包（看起来 ../../src/kineticmulti 应该可以工作）。

- Gabriel

---

是的，我忘记做了那件事。 - George Oblapenko

Answer 2

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

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

有时需要修改conf.py以导入一些源模块。此外，为了加载其方法文档（仅适用于私有类），还需要向类中添加一些文档（但我卡在这个问题上了）。

- LinearLeopard