V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
mathzhaoliang
V2EX  ›  GitHub

给项目制作文档,哪种方式更好?

  •  
  •   mathzhaoliang ·
    neozhaoliang · 2019-02-15 09:15:33 +08:00 · 1176 次点击
    这是一个创建于 1869 天前的主题,其中的信息可能已经有所发展或是发生改变。

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

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

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

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

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

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

    目前尚无回复
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   5370 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 08:34 · PVG 16:34 · LAX 01:34 · JFK 04:34
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.