Jupyter Notebook 中文书写指南

image

Jupyter Notebook 是一款优秀的 Python 交互式编程工具,并十分适合用于数据分析和机器学习工作。本指南是我个人在使用 Jupyter Notebook 撰写技术文档时遵循的格式规范。

基本规范

首先,Jupyter Notebook 内容遵循基本中文内容书写格式,该格式可以参考 中文文案排版指北 完整说明。其中需要特别注意的有:

  1. 添加空格:中英文,中文和数字,英文和数字,超链接首位需要添加一个空格。
  2. 正确专有名词用法:请使用专有名词官方默认的大小写书写格式。
  3. 中文语句中,全部使用中文全角标点符号。

补充规范

该部分为 Jupyter Notebook 撰写中文内容时的补充规范。

以独立单元格书写

以下情况,需要在 Jupyter Notebook 中使用独立单元格来呈现内容:

  1. 任意层级的标题。
  2. 完整的段落。
  3. 图片。

段落书写规范

中文段落书写要做到语句通顺,表意清晰。尽量使用书面用语,避免不规范的网络用语,口语用语等情况出现。同时,需要注意以下几点:

  1. 尽量克制使用加粗、斜体等格式,如有必要使用,同一个句话中尽量不超过 1 处。
  2. 尽量避免使用 !和 ?标点符号,正常说话。
  3. 尽量减少形容词的使用,夸张的表述。
  4. 尽量使用主动语态,而非被动语态。中文使用主动语态表述更清晰有力。

图片插入规范

插入一张图片时,默认使用 Markdown 语法规定的图片插入语句:

![image](URL)

如果图片较大,则可以使用 HTML 语法。判断图片大小合理的原则为,图片中出现的文字大小接近于正文文字大小。

<img width='700px' src="URL">

如果图片引用自外部,需要注明出处,格式为:

<img width='700px' src="URL">
<div style="color: #888; font-size: 10px; text-align: right;"><a href="URL"><i class="fa fa-copyright" aria-hidden="true"> 来源</i></a></div>

两段代码书写在同一单元格中。

代码书写规范

  1. 导入类和函数时,在首次使用的单元格中导入,而不是在 Notebook 一开始集中一次性导入。前者为 Jupyter Notebook 推荐书写方式,后者为本地 IDE 代码中推荐书写方式。