如何从文档字符串生成HTML文档

Question

我有一个Python项目，在函数里写了很多文档字符串（docstring），

我想知道怎么能在一两步之内把这些文档字符串转换成HTML格式的文档，

我只希望Sphinx能像doxygen那样，把我所有的注释或文档字符串都变成HTML文档。

我在docs文件夹下运行了sphinx-quickstart，

然后

> autodoc: automatically insert docstrings from modules (y/n) [n]: y

接着我修改了long_term_streaming_monitor/docs/source/conf.py这个配置文件，

sys.path.insert(0, os.path.abspath('../../src'))

因为我的所有源代码都放在long_term_streaming_monitor/src这个文件夹里。

生成的代码在这里 下载

我按照教程操作，但当我打开index.html时，什么都没有，HTML文件里没有列出模块和方法，链接

.
├── docs
│   ├── _build
│   │   ├── doctrees
│   │   └── html
│   │       ├── _sources
│   │       └── _static
│   ├── _static
│   ├── _templates
│   └── html
└── src
    ├── long_term_streaming_monitor
    │   ├── log
    │   ├── scripts
    │   └── tests
    │       └── log
    └── long_term_streaming_monitor_.egg-info

Answer 1

正如评论中提到的，你可以使用 sphinx.ext.autodoc。

想要快速入门可以查看这篇文章 这里。
你可以查看一个示例配置文件 这里。
另外一个小提示 - 你还可以通过 travis-sphinx 将 Travis 和 sphinx 集成，这样每次你推送带有新文档字符串的代码时，就能自动生成你的 GitHub 页面。