使用Sphinx为Python项目生成帮助文档
【摘要】 本文为前一篇 一个小而全的项目的延续：一个小而全的Python项目示例_持续学习持续开发，我是雷学委！-CSDN博客安装Sphinx（文档生成工具）pip install -U Sphinx生成默认文档配置sphinx-quickstart这里选择了不分离代码跟文档。生成文档sphinx-build -b html . _build因为上面没有选择把代码跟文档分开，所以sphinx...
本文为前一篇 一个小而全的项目的延续：
安装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文件。
:ref 指定为上面index.html页面的三个超链接，更多使用参考：
【版权声明】本文为华为云社区用户原创内容，未经允许不得转载，如需转载请自行联系原作者进行授权。如果您发现本社区中有涉嫌抄袭的内容，欢迎发送邮件进行举报，并提供相关证据，一经查实，本社区将立刻删除涉嫌侵权内容，举报邮箱：
cloudbbs@huaweicloud.com
- 点赞
- 收藏
- 关注作者
作者其他文章
评论（0）