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

您是否在 docs/source 目錄中運行了 sphinx-apidoc？ 這將生成用於制作 html 的 .rst 文件。 來自man sphinx-apidoc ，

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

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

Answer 2

正如人們所說，你應該這樣做：

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

有時還需要修改您的 conf.py 以導入一些源模塊。 以及向類添加一些文檔以加載其方法文檔（僅適用於私有類，但我一直堅持這樣做）。