作者：Zolzaya Luvsandorj
翻译：陈之炎
校对：赵茹萱

本文约2400字，建议阅读5分钟
本文为你介绍助力工作流文档化的几个实用技巧。

标签：工作流文档化

Jupyter笔记本（此文中所指的笔记本）的动人特点是能够在代码单元格旁边使用标记单元格。这些标记单元格让我们能够更清晰地记录文档，方便用户更容易理解笔记本的工作流。在这篇文章中，我将分享一些使用技巧，在无需安装任何扩展文档的情况下使得标记单元格更加丰富多彩。

图片来源：Elena Kloppenburg  

0. 复习（Refresher）

如果你一直在使用Jupyter笔记本，你可能已经对标记的基本知识有所了解。这里用一分钟时间来介绍一下标记使用的常用语法：

 

其输出为：

在复习了基本内容之后，接下来探寻一下更加复杂的标记单元格功能，以丰富文档内容，以提高可读性。

1.代码文本着色

大段的黑白文本阅读起来非常晦涩。为使黑白文本更加丰富多彩，提高文本可读性，可以为其添加色彩，突出显示和弹出关键部分。这里有三种不同的方式来为文本添加颜色：

1.1. 文本着色

使用html字体标签更改文本的颜色，可以使用颜色名称或十六进制的颜色代码：

例如：绿色文本，蓝色斜体文本和红色加粗文本

如果想探索更多的颜色名称，这可能会派上用场。如果颜色名称不能完全符合你的心意，可以用十六进制的颜色来获得更广泛的选择。这是我最喜欢用的一些十六进制颜色的资源。

1.2.  突出显示文本（高亮）

使用html 标记突出显示文本：

 

此外：可以高亮显示文本

高亮部分的文本更容易引起人们的注意。

1.3.使用告警

最后，可以使用引导告警 （ bootstrap alert）来格式化背景和字体颜色，使文本文档阅读起来更吸引人：

 

这些格式真漂亮！为文本添加颜色之后可以立即提高Notebook文档的可读性，使关键之处更加突出，阅读文档起来更加生动。这样，快速浏览和快速获取要点就变得更容易一些。

2. 适当格式化文本

另一种丰富文档的方法是使用相应的富文格式，下面来看看三种不同的文本格式化方法：

2.1 用LaTeX插入数学方程式

当需要在笔记本文档中引用数学方程时，可以使用$，利用LaTeX来显示数学公式：

 

当方程在双$之中时，它将在中心对齐。如果使用单个$，它将保持左对齐。或者，也可以使用这个语法来编写公式：

2.2.  使用代码块

有时，可以在标记单元格中显示代码引用，而非在代码单元格中运行它们。可以使用单个反向引号`来显示一个代码块：

 

对于大段的代码块，可以使用三重反向引号 ：

 

如果在第一个三重引号 `之后指定了语言名称，那么将对代码块进行适当的彩色格式化：

 

2.3. 使用引用缩进

缩进法是格式化文本以提高可读性的另一种方法，可以用>添加缩进：

 

3.  添加媒体

“一幅图胜过千言万语。”

文档并不一定要用文字表示，图片和其他媒体可以帮助我们交流那些原本很难用文本来表达的想法。添加相关媒体是使文档更加丰富多彩的另一种好方法。

3.1. 插入GIF图像

可以使用html标记来向标记单元格中添加图像：

 

Pipeline, ColumnTransformer and FeatureUnion explained

这里，example.jpeg保存在与Notebook同一个文件夹中。可以使用宽度或高度参数,对图像的大小进行修改。例如，利用 将显示的图像大小调整为所需宽度，同时保持宽度与高度比。

如果在静态图像中添加图表或表格等可视化数据还不足以完全捕捉到想要传达的内容，那么使用完全相同的语法结构，可以嵌入GIF（动图）：

数据科学的Git导论

文件的路径也可以是一个web链接：

 

3.2.插入视频

“一段（一分钟）的视频价值180万字。”

如果GIF还不足够，下一步便是使用视频，可以使用html

 

例如，对如何完成任务进行录屏之后，将其保存为视频文件，并将该视频插入到Notebook中，方便用户日后使用。

3.3.  添加形状和表情符号

大段冗长的纯文本读起来可能相当无聊，也不值得阅读，优雅地添加形状和表情符号可以使得文本更有趣，阅读起来更引人入胜：

 

这里有更多的形状（和表情符号），这个表情符号小单在搜索表情符号时很有用。

这些便是丰富Jupyter笔记本文档的技巧。大家可能不会同时使用所有上述功能，但是知道如何使用可以让你有备无患。

 图片来源：Chris Lawton

希望访问更多像这样的内容？Medium会员可以无限访问媒体上的任何文章。如果你使用我的推荐链接成为会员，你的部分会费将直接支持我。

谢谢阅读我的文章。如果想了解更多关于标记的信息，请查看本指南。如果你感兴趣，下面有我的一些帖子的链接：

• 有用的IPython魔法命令

（https://towardsdatascience.com/useful-ipython-magic-commands-245e6c024711）

• 面向数据科学的Python虚拟环境介绍

（https://towardsdatascience.com/introduction-to-python-virtual-environment-for-data-science-3c216929f1a7）

• pandas 用户的5个技巧

（https://towardsdatascience.com/5-tips-for-pandas-users-e73681d16d17）

• 在 pandas中编写5个常见的SQL查询

（https://towardsdatascience.com/writing-5-common-sql-queries-in-pandas-90b52f17ad76）

原文标题：

Enrich your Jupyter Notebook with these tips

原文链接：

https://towardsdatascience.com/enrich-your-jupyter-notebook-with-these-tips-55c8ead25255?source=collection_home

编辑：于腾凯

校对：杨学俊

译者简介

陈之炎，北京交通大学通信与控制工程专业毕业，获得工学硕士学位，历任长城计算机软件与系统公司工程师，大唐微电子公司工程师，现任北京吾译超群科技有限公司技术支持。目前从事智能化翻译教学系统的运营和维护，在人工智能深度学习和自然语言处理（NLP）方面积累有一定的经验。业余时间喜爱翻译创作，翻译作品主要有：IEC-ISO 7816、伊拉克石油工程项目、新财税主义宣言等等，其中中译英作品“新财税主义宣言”在GLOBAL TIMES正式发表。能够利用业余时间加入到THU 数据派平台的翻译志愿者小组，希望能和大家一起交流分享，共同进步

翻译组招募信息

工作内容：需要一颗细致的心，将选取好的外文文章翻译成流畅的中文。如果你是数据科学/统计学/计算机类的留学生，或在海外从事相关工作，或对自己外语水平有信心的朋友欢迎加入翻译小组。

你能得到：定期的翻译培训提高志愿者的翻译水平，提高对于数据科学前沿的认知，海外的朋友可以和国内技术应用发展保持联系，THU数据派产学研的背景为志愿者带来好的发展机遇。

其他福利：来自于名企的数据科学工作者，北大清华以及海外等名校学生他们都将成为你在翻译小组的伙伴。

点击文末“阅读原文”加入数据派团队~

转载须知

如需转载，请在开篇显著位置注明作者和出处（转自：数据派ID：DatapiTHU），并在文章结尾放置数据派醒目二维码。有原创标识文章，请发送【文章名称-待授权公众号名称及ID】至联系邮箱，申请白名单授权并按要求编辑。

发布后请将链接反馈至联系邮箱（见下方）。未经许可的转载以及改编者，我们将依法追究其法律责任。

点击“阅读原文”拥抱组织