绑定完请刷新页面
取消
刷新

分享好友

×
取消 复制
坑踩过了让你5分钟速成Sphinx为项目生成帮助文档
2022-05-11 15:53:03

安装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/


作者:雷学委
链接:https://juejin.cn/post/6997810123863228424

分享好友

分享这个小栈给你的朋友们,一起进步吧。

Sphinx
创建时间:2022-03-21 11:14:26
Sphinx
展开
订阅须知

• 所有用户可根据关注领域订阅专区或所有专区

• 付费订阅:虚拟交易,一经交易不退款;若特殊情况,可3日内客服咨询

• 专区发布评论属默认订阅所评论专区(除付费小栈外)

技术专家

查看更多
  • itt0918
    专家
戳我,来吐槽~