安装Sphinx（文档生成工具）

pip install -U Sphinx

生成默认文档配置

sphinx-quickstart

这里选择了不分离代码跟文档。

生成文档

sphinx-build -b html . _build

因为上面没有选择把代码跟文档分开，所以sphinx扫描了所有目录而不是我们模块的代码，出现下面错误：

检查一致性... /Users/mac/python/python_sample/lib/python3.8/site-packages/Jinja2-2.11.3.dist-info/LICENSE.rst: WARNING: 文档没有加入到任何目录树中

/Users/mac/python/python_sample/lib/python3.8/site-packages/MarkupSafe-1.1.1.dist-info/LICENSE.rst: WARNING: 文档没有加入到任何目录树中

该错误可以忽略，并不妨碍文档生成。

查看默认生成的文档

打开浏览器出入当前目录/_build/index.html,  即可查看。

Sphinx如何运作？

上面使用sphinx-quickstart 生成默认文档声明文件Makefile和conf.py, Makefile指定项目信息和source目录（这里是sphinx的source）。

然后sphinx根据找到的source（*.rst, 后缀为.rst 文件)，并解析生成同名的html文件。

学委开发经验小Tips

整个过程很快，添加这些问题生成文档，好的时候在项目初期！

随着时间推进，项目会发展，比如各种API都要说生成文档那得消耗更多时间。

越往后越花费时间，这是肯定的。

:ref 指定为上面index.html页面的三个超链接，更多使用参考：

www.sphinx.org.cn/

相关文章