macOS使用Jupyter Notebook简介

2017-09-29|Categories: macOS|Tags: , |

What

The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and explanatory text. Uses include: data cleaning and transformation, numerical simulation, statistical modeling, machine learning and much more.

Jupyter Notebook是一个开源免费的web应用程序,在浏览器里运行,功能强大、安装方便、使用简单,主要用于大数据和机器学习,可以很方便的编写、展示、分享包含程序代码、方程式、数学图形、格式化文本的文档。

官网上展示了正在使用Jupyter的机构:

Why

以上罗列的功能,其实Markdown也可以做到,现如今Markdown编辑器一抓一大把,为什么还要使用Jupyter?

原因很简单:Markdown虽然可以编辑包含程序代码的文件,但不能让这些代码在文件里面直接运行、输出,而Jupyter可以完美实现这一点,这就是官方介绍的「live code」——是活的代码,不是死的文字。

除了live code这个杀手锏功能,Jupyter也完美支持Markdown,可以非常方便的格式化文本。

When, Where, Who

live code非常适合程序员记录代码笔记:输入代码,运行后输出结果直接显示在代码下方,更改代码之后重新运行就可以获取新的输出,不再需要繁琐的截图、复制、粘贴。

How

安装Jupyter Notebook

通过Anaconda安装

这是Jupyter官方推荐初学者使用的安装方法,Anaconda支持Windows、macOS、Linux平台,提供图形化安装界面,会自动安装所有的相关软件,直接到Anaconda官方下载页面下载即可。

通过pip安装

喜欢命令行的用户可以使用pip安装,官方推荐使用Python 3:

pip3 install --upgrade pip
pip3 install jupyter

如果使用Python 2,把pip3改为pip即可。

运行Jupyter

在命令行启动Notebook server

Jupyter可以从任意目录启动,但为了集中管理笔记,我会新建一个专用目录,然后从这个目录启动server:

mkdir jupyter-notebook
cd jupyter-notebook
jupyter notebook

server启动成功之后,默认浏览器会自动打开,界面如下:

设置alias

jupyter notebook这个命令太长,输入不便,于是我在~/.bash_profile设置了alias:

alias jn='jupyter notebook'

从指定IP和端口启动server

默认的启动地址是localhost:8888,有时需要从其它地址启动,以便从局域网的其它机器访问:

jupyter notebook --ip 192.168.6.200 --port 9999

然后在局域网其它机器的浏览器地址栏输入http://192.168.6.200:9999,需要输入密码或token:

通过jupyter notebook list找到当前任务的token并复制粘贴,就是token=后面那一长串字符(不包含空格和空格后面的部分):

在浏览器里编辑文件

打开浏览器首先看到的是当前目录的所有子目录和文件,如果当前目录是空的,可以点击右上角的New按钮新建目录或文件:

默认在Notebook下方只有Python,这就是Jupyter的Kernel,其实就是Jupyter支持的编程语言,Jupyter已经支持超过40种语言,但默认只安装了Python,其它的Kernel按需安装即可。

新建文件会在新标签页打开,默认有一个空的cell,cell的类型是Code,处于edit mode,可以直接输入代码。

如果想输入Markdown文本:

  • 首先按esc键或ctrl-m组合键退出edit mode,进入command mode
  • 再按m把cell类型改为Markdown
  • 再按enter进入edit mode输入内容。

不管哪种类型的cell,输入完毕之后,都可以按ctrl-enter组合键来运行,Code类型的cell会输出运行结果,Markdown类型的cell会把纯文本渲染成对应的格式。也可以按alt-enter组合键运行当前cell,并在下方插入新的cell。

Jupyter提供了非常多的快捷键,可以显著提升效率,但最重要的快捷键一定是shift-cmd-p,和Sublime Text一样,可以弹出「命令面板」查找所有命令。即使刚开始记不住这个最重要的快捷键,工具栏最右边还提供了一个「键盘」按钮,点击就是同样的效果。

如果只想查看那些设置了快捷键的命令,按h即可,前提是你必须处于command mode

安装Kernel

官方负责维护的Kernel有三种:Julia、Python、R,Jupyter这个名称就源于这三种Kernel。绝大部分的Kernel由社区维护

我需要安装Bash Kernel,步骤如下:

pip install bash_kernel
python -m bash_kernel.install

正常启动server就可以新建Kernel为Bash的文件。

安装扩展

Jupyter笔记包含了文本、代码、图形,很容易就变得很长,这时候就需要一个能够在文件内快速跳转的大纲,这个功能需要安装扩展来实现。

jupyter_contrib_nbextensions是一个扩展「集中营」,包含了一系列从网上收集的扩展,可以让扩展的安装、配置、启用、禁用变得非常方便,安装方法如下:

pip install jupyter_contrib_nbextensions
jupyter contrib nbextension install --user

更多安装方式详见Jupyter notebook extensions官网

安装成功之后,可以通过命令行启用、禁用某个扩展,但不推荐,因为有更方便直观的方式:

支持中文的PDF导出

Jupyter默认支持导出为多种格式,但导出PDF比较麻烦,尤其是包含中文的PDF。

本来想通过Chrome内置的打印功能另存为PDF,但不知为何总是有bug:

最终只能通过Jupyter内置的方式导出PDF,步骤如下:

安装pandoc

brew install pandoc

下载MacTeX

wget http://tug.org/cgi-bin/mactex-download/MacTeX.pkg

这玩意是一个「TeX发行版 for macOS」,个头非常大:安装包3.14G!关键是下载速度并不快,为了保证一次下载成功,我特意用Windows虚拟机里的Internet Download Manager来下载,还好官方自动把下载源切换到了中科大的镜像服务器,下载速度最低也有1M/s。

下载完毕之后,务必要验证完整性,如果验证失败,只能重新下载:

touch mactex.pkg.md5
vim mactex.pkg.md5
    # copy & paste below line into vim, then `:wq`
    # there must be 2 spaces between md5 string and file name
    a04828f1ffacc0bf9b48879b57794c2b  MacTeX.pkg
md5sum -c mactex.pkg.md5

不同版本的md5值不一样,这里的md5值对应MacTeX-2017,可以在MacTeX官方下载页面找到。

不要下载BasicTeX

因为MacTeX实在太大,有网友推荐用体积较小的BasicTeX加上必要的包来替代,二者虽同出一家,但这个方案可能仅仅适合非常了解TeX的用户,我实际测试的结果是不行——会出现各种让人眼花缭乱的报错,换成MacTeX就一切正常。

安装MacTeX

MacTeX.pkg双击就可以安装,安装完成要占用接近6G的磁盘空间。安装完成建议重启电脑。

更新MacTeX

这一步非常耗费时间,先不要执行,如果执行完后面的步骤还是无法输出中文PDF再回来执行。

sudo tlmgr update --self
sudo tlmgr update --all
sudo fmtutil-sys --all

查找并修改Jupyter的导出模板文件

模板文件名为article.tplx,根据Jupyter安装方法的不同,位于不同位置,可以通过以下命令查找:

find / -name 'article.tplx'

我是通过pip安装的,所以完整路径是:

/usr/local/lib/python2.7/site-packages/nbconvert/templates/latex/article.tplx

修改article.tplx
  • 方法一:把\documentclass[11pt]{article}article改为ctexart,变成\documentclass[11pt]{ctexart}
  • 方法二:在\documentclass[11pt]{article}下面添加一行\usepackage{ctex},变成:
    \documentclass[11pt]{article}
    \usepackage{ctex}
    

旧版Jupyter的模板文件中可能没有[11pt],不影响转换。

导出PDF

完成以上步骤之后,就可以通过菜单导出PDF了。

也可以从命令行把.ipynb文件转换成PDF:

# convert `.ipynb` to `.tex`
ipython nbconvert --to latex example.ipynb

# convert `.tex` to `.pdf`
xelatex example.tex

导出的PDF效果如下(通过PDF Expert打开):

总结

Jupyter很强大也很方便,非常适合程序员记录代码笔记,但导出中文PDF比较麻烦,没有硬性需要的话,不建议折腾。

Leave A Comment