Sphinx autodoc不导入任何内容？

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.

那么，我哪里做错了呢？

Answer 1

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

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

有时候，你需要修改你的conf.py文件，以便导入一些源代码模块。同时，还需要在类中添加一些文档，以便加载它的方法文档（这可能只适用于私有类，但我在这方面遇到了一些困难）。

Answer 2

你有没有在 docs/source 这个文件夹里运行 sphinx-apidoc 呢？这样做会生成用于制作 HTML 的 .rst 文件。从 man sphinx-apidoc 可以看到，

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

你至少需要提供两个东西：一个是 outputdir（这是 .rst 文件要放的地方，./ 应该可以用），另一个是 sourcedir（这个应该指向你的包，像 ../../src/kineticmulti 应该可以用）