How2CommentIpynb - 101camp/playground GitHub Wiki

现在大家很多代码, 都在 jupyter notebook 内完成, 当发现别人代码某部分有问题时, 通过 comment to commit 很不容易定位到错误语句进行评论.

• gh-repo. 内置了完备的点评机制
• 访问路径 -> History -> Commit -> 点击对应行追加/回复/emoji 评论

问题在:

• 只针对当前 commit 部分
• 而无法简单的从当前最新代码全貌中对应行进行点评
• Blame 视图解决部分问题
  • 但是, 并不直观
  • 同时进入也非常费时

大家已经习惯了在 ipynb 的本地交互web 界面中

夹叙
夹议
加代码
以及运行结果

这种综合形式来同时记载下来:

• 问题/命题的阐述
• 相关模块/函式/代码的验证
• 可用函式的形成/调试/...

问题在, 怼员要进行讨论时,

• ipynb 是以 JSON 格式写入文件的
• git 对其可以完备的进行版本管理
• 但是, 此时, 在 gh-commit comment 界面中,就难以完成点评了
• 因为, commit 记录的是 JSON 格式的文本差异, 从中难以定位想点评的部分代码/运行结果/文档了

~> ipython-contrib/jupyter_contrib_nbextensions: A collection of various notebook extensions for Jupyter

好在 Jupyter 的生态非常完备, 早已包含了对应的解决形式之一

参考: 6818bb4

对 YH 的一则 ipynb 点评:

• git pl ~同步最新成果
• juypter notebook 本地运行
• 通过 chrome 进入对应有兴趣的目录
• 打开想学习的 ipynb
• 发现问题使用 b / a 在对应节点前后追加一个节点
• 用 m 将当前新增节点变成 markdown 文档节点
• enter 进入, 增补自己的问题/建议/讨论....
• 当然, 为了给原作者一个强烈的提示:
  • 对应给出合理的标题
  • 以及标题约定格式

类似:

[性质]日期[作者](主题)
e.g
ASK18.1.30DAMA
ISSUE18.1.30ZQ~代码注释

这样, 如果都配置有 TOC2 扩展的话, 就可以在同步了代码后, 立即从目录树中看到点评引发的变化

然后, 自然的进行对应回复, 并改变标题

<-- 简单的说:

就是将 ipynb 每一个文件
视为 mailling-list 中的一个线索
大家使用标准的 bottom-post 形式
来完成对应讨论/增补/回复/修订/...

TLog