使用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 可以做哪些事情——一些很好的項目筆記