使用Jupyter Notebook编写技术文档

1、jupyter Notebook的组成

　　这里它的组件及其工程构成，帮助大家更好的用好jupyter Notebook

组件

Jupyter Notebook结合了三个组件：

• 笔记本Web应用程序：交互式Web应用程序，用于交互编写和运行代码以及编写笔记本文档。
• 内核：笔记本Web应用程序启动的独立进程，它以给定语言运行用户代码，并将输出返回给笔记本Web应用程序。内核还处理诸如交互式小部件，选项卡完成和内省的计算。
• 笔记本文档：自包含文档，其中包含笔记本Web应用程序中可见的所有内容的表示，包括计算的输入和输出，叙述性文本，方程式，图像以及对象的富媒体表示。每个笔记本文档都有自己的内核。

jupyter notebook的工程组件

笔记本Web应用程序使用户能够：

• 在浏览器中编辑代码，自动语法高亮，缩进和制表符完成/内省。
• 从浏览器运行代码，将计算结果附加到生成它们的代码。
• 查看富媒体表示的计算结果，如HTML，LaTeX，PNG，SVG，PDF等。
• 创建并使用交互式JavaScript小部件，它将交互式用户界面控件和可视化绑定到反应式内核端计算。
• 使用 Markdown标记语言撰写叙述性文字。
• 使用LaTeX语法在Markdown中包含MathJax在浏览器中呈现的 数学公式。

通过Jupyter的内核和消息体系结构，Notebook允许代码以各种不同的编程语言运行。对于用户打开的每个笔记本文档，Web应用程序启动一个运行该笔记本代码的内核。每个内核都能够以单一编程语言运行代码，并且有以下语言提供的内核：

• Python(https://github.com/ipython/ipython)
• Julia (https://github.com/JuliaLang/IJulia.jl)
• R (https://github.com/IRkernel/IRkernel)
• Ruby (https://github.com/minrk/iruby)
• Haskell (https://github.com/gibiansky/IHaskell)
• Scala (https://github.com/Bridgewater/scala-notebook)
• node.js (https://gist.github.com/Carreau/4279371)
• Go (https://github.com/takluyver/igo)

　　在内部，笔记本文档是 `JSON <https://en.wikipedia.org/wiki/JSON>`__数据的二进制值`base64 <http://en.wikipedia.org/wiki/Base64>`__编码。这使得它们可以通过任何编程语言以编程方式读取和操作。因为JSON是一种文本格式，所以笔记本文件是版本控

制友好的。

 

2、创建新环境并导入kernel

对于不是直接安装anaconda的用户来说，首先需要安装 ipykernel 模块

pip install ipykernel

　然后用类似于

conda create --name python34 python=3.4

　　的指令来创建新的环境，然后对环境进行配置及必要第三方包的安装即可创建一个新的环境。关于第三方包的管理和环境的配置，请看jupyter Notebook环境搭建。

当然你也可以通过ananconda navigator来进行环境的管理：

环境创建完成后，打开Jupyter后，我们点击new，会发现只有一个kernel

 如果我们希望使用其他环境，需要导入其他环境到kernel中来。就需要用到以下命令：

1）查看jupyter notebook kernel指令

jupyter kernelspec list

2）为jupyter notebook 添加新的kernel

python -m ipykernel install --name kernelname

3）删除notebook kernel

jupyter kernelspec remove kernelname

　　如下为将配置好了的python2.7的环境添加到jupyter notebook kernel中

完成此操作后，刷新jupyter notebook的浏览器界面，再次点击new就可以看到自己添加的kernel了：

 

 

3、jupyter notebook界面介绍

　　打开jupyter Notebook，点击右边的NEW，选择自己要添加的类型，这里选择python 3

就会打开如下界面

 

 

1）鼠标导航

当您创建新的笔记本文档时，您将看到 笔记本名称，菜单栏，工具栏和空白代码单元。

笔记本名称：显示在页面顶部Jupyter徽标旁边的名称反映了该.ipynb文件的名称。点击笔记本名称会弹出一个对话框，让您对其进行重命名。因此，将浏览器中的“Untitled0”重命名为“我的第一个笔记本”，将Untitled0.ipynb文件重命名 为。My first notebook.ipynb

菜单栏：菜单栏提供了可用于操作笔记本功能的不同选项。

工具栏：通过点击图标，工具栏提供了在笔记本中执行最常用操作的快速方法。

单元格：单元格有三种类型的单元：代码单元，降价单元和原始单元。每个单元格都是一个代码单元格，但其类型可以通过使用工具栏上的下拉菜单或通过键盘快捷键进行更改 。

　　　　：1）码单元（code）：可以编辑和编写新代码，以饱满的语法高亮和标签完成。您使用的编程语言取决于内核，而默认内核（IPython）运行Python代码。

　　　　　2）文本单元（markdown）：可以通过文字方式记录计算过程，使用丰富文本将描述性文本与代码交替使用。

　　　　　　　　　　　　　　　　　　如果您想为文档提供结构，则可以使用markdown作标题。Markdown标题由1到6个#组成，#后跟一个空格和部分的标题。

　　　　　　　　　　　　　　　　　　Markdown单元格中，还可以使用标准的LaTeX符号以直接方式包括数学：$...$用于内联数学和 $$...$$显示的数学。

　　　　　3)原始单元（Raw cells）：原始单元格提供了一个可以直接编写输出的位置。

2、编辑模式

　　从IPython 2.0开始，Jupyter Notebook具有模态用户界面。这意味着键盘会根据笔记本所处的模式执行不同的操作。有两种模式：编辑模式和命令模式。编辑模式由绿色单元格边框和编辑器区域中显示的提示指示，如下所示：

　　如果jupyter的单元格边框为绿色，说明当前模式为编辑模式。

　　

　　如果jupyter的单元格边框为蓝色，说明当前模式为命令模式。你可以通过快捷方式来对编辑模式进行切换。你可以通过help->keyboard shortcuts来查询相关快捷方式。

3、键盘导航

 　　之前已经说过了，jupyter notebook提供了两组快捷方式的操作，值得一提的是，两组快捷方式在不同编辑模式下有效。我们可以通过以下顺序粗略的学习下命令模式快捷方式：

1. 基本导航：enter切换到编辑模式，shift-enter运行当前单元，up/k向上一个单元切换，down/j向下一个单元切换
2. 保存笔记本： s保存笔记本
3. 更改单元格类型：y切换单元为code模式，m切换单元为文本单元，1-6转换为第1—6类标题

4. 单元插入：a在这个单元前插入一个单元，b在这个单元后插入一个单元。
5. 单元格编辑：x剪切当前单元，c复制当前单元，v粘贴单元到当前位置，d删除单元，z撤销当前单元的操作。
6. 内核操作：i中断当前内核，0重启当前内核（都按两次）

 

4、运行代码

　　讲完jupyter的组件、界面及快捷方式后，我们可以通过一个实例来进一步加强了解。下面为一个基本的技术文档的编写：

首先，书写标题和作者，以heading模式输入，输入如下：

然后就可以输入文本的主要内容了

 

这样，一个基本的带源码的技术文档就写出来了，然后我们需要做的工作就是运行代码，查看代码是否有误，并查看运行结果，点击工具栏的就可以看到代码的运行效果及一份完整的技术文档。

 

5、导入公式、图表、视频

　　上面只是一个简单的例子，篇幅小，也没有插入公式等解释性插件。有时候，我们需要插入公式、图表等本地文件对界面进行解释性说明，让读者对整个原理及过程有更加详细的了解，这里就重点讲解下公式、图表和视频的插入方法。

 1）插入公式

　　对于公式的插入，如果你对Latex不熟悉，可以登陆Latex编辑器，然后在编辑器直接输入公式就可以生成公式对应的Latex代码了。如果你想学习一些Latex的基本知识，请看参考资料中的在博客中使用LaTeX插入数学公式。这里就不对相关语法做讲解了。

　　创建完成后，我们就可以通过LaTex插入数学公示了，生成LaTex码后，复制后打开你的notebook。如果你希望公式居中，则用$$...$$将你的公式括起来。否则，则用$...$括起来即可（值得注意的是：此时你的cell模式应该为markdown）

下面为一个实例及其运行结果：

　　

运行结果如下：

 

 2、插入本地文件

　　如果你的notebook中有本地文件，则可以直接在markdonw单元格中使用这些本地文件，使用方法如下：

A | B
- | - 
![alt](yourimg1.jpg) | ![alt](yourimg2.jpg)

　　在windows下你可以直接Ctrl+C复制，然后在cell中Ctrl+V粘贴。这里还是将代码贴出，以供参考学习：

![test.jpg](./test.jpg)

　　这里已将test.jpg文件移动到Jupter路径下。

运行程序，结果如下：

 

当然，你还可以导入网络链接的图片和视频，这里只需要将路径改为对应的网络链接，并将文件名改为对应的文件名即可。如下所示：

![List vs Generator](https://raw.github.com/yoavram/CS1001.py/master/list_vs_generator.png)

 

 

6、使用Jupyter制作slides

 　　在制作slides时，首先在view中，将视图切换到Slidesshow

      在要编辑的文本行中，slice type中选择slice或sub-slice。若选择slice，slice之间是左右切换，每个slice和sub-slice相当于一张幻灯片。同一个slice和它的菜单sub-slice之间是上下切换。

完成slice的制作后，打开cmd命令框，cd到ipynb文件目录下，我们就可以将.ipynb文件转换生成.html文件，以网页的形式展示幻灯片。使用如下指令即可：

jupyter-nbconvert --to slides 源.ipynb --reveal-prefix  'https://cdn.bootcss.com/reveal.js/3.5.0' --output 输出的目标文件名

　　

完成后就可以在目录中看到生成的.html文件，打开便可看到生成的slider

 

 

 

 

7、导入外部代码

比如有一个test.py文件，需要将其载入到jupyter的一个cell中

在需要导入该段代码的cell中输入

%load test.py #test.py是当前路径下的一个python文件  

　　如下图所示：

运行后，可以看到代码导入进来了：

 

 

8、将Jupyter笔记本导出为模块

　　想要使用jupyter中的代码，你可以保存为.py模式然后进行修改添加。如下所示。

 

9、魔术命令

在 IPython 的会话环境中，所有文件都可以通过 %run 命令来当做脚本执行，并且文件中的变量也会随即导入当前命名空间。

即，对于一个模块文件，你对他使用 %run 命令的效果和 from module import * 相同

这种以 % 开头的命令在 IPython 中被称为魔术命令，用于加强 shell 的功能。

常用的魔术命令有： 

对魔术命令不熟悉的话可以通过 %magic 查看详细文档；对某一个命令不熟悉的话，可以通过 %cmd? 内省机制查看特定文档

 

10、nbextension的安装

　　首先，PIP安装nbextension的python包。

pip install jupyter_contrib_nbextensions

　　然后将nbextensions的javascript和css文件复制到jupyter服务器的搜索目录中，并编辑一些jupyter配置文件。

jupyter contrib nbextension install --user

　　该命令执行两件事：安装nbextension文件，并编辑nbconvert配置文件。第一部分基本上是笔记本提供的一个包装，并将相关的javascript和css文件复制到适当的jupyter数据目录中。第二部分编辑配置文件， 如下面的选项中所述。该命令可以采用与jupyter提供的版本大部分相同的选项，包括jupyter nbextension installjupyter_nbconvert_config.jsonjupyter_notebook_config.json

　　最后，要使用nbextension，你还需要启用它，它会通知笔记本界面加载它。为此，你需要安装 jupyter_nbextensions_configurator 服务器扩展。

conda install -c conda-forge jupyter_nbextensions_configurator
或者
安装
pip install jupyter_nbextensions_configurator
加载服务器扩展
jupyter nbextensions_configurator enable --user

　　完成后，重新启动笔记本服务器。此时，可以看到多出了一个nbextension

　　点进去后，勾选confolding即可。

关于nbextension可扩展的功能，这里不详细介绍，你可以参考相关技术文档，这里举一个python2 to python3工具的例子。

　　首先，在nbextension的界面中勾选，下面，新建一个单元格，输入如下python2版本代码：

#function and print statements
def f(x):
    print 'The "input" is %s \n and \" this sentence\
    is on two lines'%x
    print type(unicode('this is like a python3 str type'))

#internet connexion

import urllib2
req=urllib.Request(url='http://localhost/cgi-bin/test.cgi',
                  data='This data is passed to stdin of the CGI')
f = urllib2.urlopen(req)
print f.read()

#unicode string
s=u'was ever feather so lightly blown to and fro as this multitude '

　　

 转换之后，可以得到如下结果：

 

 对于安装了anaconda的用户来说，可以通过直接打开jupyterlab，来加载一个成熟界面：

 

 

 

 

11、上传自己的notebook到github上

　　首先，为一个项目创建一个仓库。

创建成功后看到到下图，途中地址是这个仓库的地址

 

打开git  bash

cd到你要上传的文件的目录下，输入git init在当前项目的目录中生成本地的git管理

输入git add. 将项目上所有的文件添加到仓库中，如果想添加某个特定的文件，只需把.换成这个特定的文件名即可。

然后配置你的git上你个人的用户名称和电子邮件地址，然后运行git commit上传你的notebook。

-m "first commit"表示你对这次提交的注释，双引号里面的内容可以根据个人的需要改。

然后输入git remote add origin https://github.com/noticeable/python_notebook.git将本地的仓库关联到github上，

 

最后，通过git push -u origin master把笔记上传到github仓库。

最后，打开你的仓库链接，可以看到你上传的项目。

其中的Untitled0.ipyn便是本文的笔记。最后还有一些很好的项目分享，请看参考资料。

 

参考资料

Jupyter Notebook Document

Jupyter Notebook介绍、安装及使用教程

Documentation

A gallery of interesting Jupyter Notebooks

Getting started with the Jupyter notebook (part 1)

jupyter notebook添加kernel

MathJax basic tutorial and quick reference

在博客中使用LaTeX插入数学公式

关于Jupyter Notebook的28个技巧

Markdown 语法说明 (简体中文版) / (点击查看快速入门)

Markdown 语法说明 (简体中文版) 

MarkDown 高级操作

IPython

手把手教新手小白在window把自己的项目上传到github

Unofficial Jupyter Notebook Extensions

nbviewer——A simple way to share Jupyter Notebooks

jupyter notebook 可以做哪些事情——一些很好的项目笔记