给项目制作文档，哪种方式更好？

[mathzhaoliang]

如题，我有一个 python 项目，有许多 .py 文件组成，文件之间关联程度不大。我现在想给项目加上文档，现在有两种选择：

1. 用 jupyter notebook 的形式演示每一个脚本是怎样工作的；
2. 用 sphinx 的方式将文档放在一个项目主页上。

我觉得前者维护起来比较容易，毕竟代码和文档都在一个 ipynb 文件里，修改代码的同时文档也就改了，用户也比较省事，不用再去翻文档了。

后者有个明显的好处就是可以放一些外部资源，比如图片、视频、甚至 js 动画演示等等。缺点就是每次 push 了新代码以后还要去修改文档上传。

我还有一个感觉就是 jupyter 的字体和 Latex 渲染都不好看，相反如果用 hexo/hugo 搭建 github pages 的话可以实现更漂亮的界面和更丰富的功能。

大家觉得哪一种比较合适？