自己制作本地的Jupyter Book

发表于 | 分类于 | 阅读次数

前面一文记录：筛选写书工具的艰苦经历简要记录的自己尝试几种工具的艰苦努力，最后的结论是”Word + Calibre” 制造常用的电子书(DOCX, PDF, EPUB，MOBI和azw3等)还是够用的。不过，还是觉得要写一本使用Python 完成编程的书(近期的计划是商务视角下的数据分析，和高性能计算)​，能够编纂配套的代码展示也是有必要的，所以，又了解了下使用Jupyter NoteBook 编写Python 代码书的技巧，汇总于此。

关于 Jupyter Notebook

Jupyter notebook 由 Fernando Perez 在 2001 发起。它的目标是提供 “Tools for the entire life cycle of research computing.” 如果说 Python 是数据科学操作的引擎，那么 IPython 就是交互式的控制面板。

The guy at left is Fernando Perez

  • IPython 只是为 NumPy、Scipy、Pandas、Matplotlib 等包提供一个交互式接口。其本身并不提供科学计算的功能。这些工具组合在一起，形成了可以匹敌如 Matlab、Mathmatic 这些复杂工具的科学计算框架。
  • IPython 是一种交互式 shell，与普通的 Python shell 相似，但具有一些很好的功能（例如语法高亮显示和代码补全）。notebook 的工作方式是：你通过浏览器连接到该服务器，而 notebook 呈现为 Web 应用。你在 Web 应用中编写的代码（你在浏览器中看到的 notebook）通过该服务器发送给内核 IPython 内核（在后台运行的 IPython 应用程序），内核运行代码，并将结果发送回该服务器。之后，任何输出都会返回到浏览器中。
  • Jupyter Notebook（Jupyter命名是取自Julia语言，Python语言，R语言，曾用名iPython Notebook）原来也叫iPython Notebook，顾名思义，它和Python关系紧密。Jupyter Notebook 是一个开源的 Web 应用程序，便于创建和共享文学化程序文档，支持40多种编程语言，支持实时代码、数学方程、可视化和 Markdown，其用途包括数据清理和转换、数值模拟、统计建模、机器学习等等。目前，数据挖掘领域中最热门的比赛 Kaggle 里的资料都是 Jupyter 格式。
  • 对于机器学习和数据科学的工作者来说，如果都应该使用或必须使用一种工具，那毫无疑问，它就是Jupyter Notebook；数据科学家可以在上面创建和共享自己的文档，从实现代码到全面报告，Jupyter Notebook大大简化了开发者的工作流程，帮助他们实现更高的生产力和更简单的多人协作。也正是因为如此，它一直以来都是数据科学家们最喜欢的工具之一。

Jupyter Book 所需要的工具 - Anaconda 的Jupyter NoteBook就不错

官方在文档中强烈建议新用户用Anaconda打包安装Python和Anaconda——所谓懒人方法，小白必备。其实除了提到的两个工具，Anaconda还包含数据科学和机器学习中经常需要用到的各种软件包，只需下载、解压、安装，所有工具就都一步到位了。

其中，”C:\Users\86150”就是默认的根目录。

Jupyter Book 生成Demo Book - 很简单的指令

在安装好Jupyter NoteBook 后，创建一个Jupyter Book 的Demo 是很简单的事。

管理员身份打开 Anaconda Prompt

创建目录，在Prompt 中定位置该目录，执行jupyter-book create mybookname --demo

会自动生成Jupyter Book 的目录。

使用Jupyter NoteBook 编辑 MD, ipynb等 - 另文叙述

执行 jupyter-book build mybookname会自动Build 相应的HTML

不过，那些HTML在浏览器直接打开是乱的

说是可以推送到 Git Pages，借助GP 的 Jekyll 来得到 – 后面有本地构建Jupyter 书 对应的 Web Site的方法

想要像 Git Pages 那样网页显示 Jupyter Book，需要 Ruby, Jekyll，Gem 和 Bundle – 一定要使用国内的源！

要构建Jupyter Book 本地的Web site，需要类似 Git Hub 的环境，即 Ruby 和 Jekyll。

安装 Ruby

得安装 Jekyll – Gem 和 Bundle还是要国内的源

gem install jekyll

安装 Jekyll 的指令很简单，就是gem install jekyll，但是，该指令默认是访问国外的网站，那速度是不能忍受的。所以，必须换成国内的源。

先换国内的源

1
2
3
4
$ gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
$ gem sources -l
https://gems.ruby-china.com
# 确保只有 gems.ruby-china.com

上面的gems.ruby-china.com只是举例(我安装时倒是测试通过了)，也还有其他国内的源可用的。

再install Jekyll 就飞快了！

gem install jekyll-paginate

gem install bundle

在没换国内源前，虽然也能成功，但是，jekyll -v 就失败了 – 缺很多东西！

即便是安装MSYS2 and MINGW development toolchain – Jekyll -v 还是失败。

虽然似乎可以按照错误提示安装对应的包，但是，太过麻烦！

还是使用Bundle 来的方便：能将所依赖的资源自动安装完成 – 也要国内的源

1
$ bundle config mirror.https://rubygems.org https://gems.ruby-china.com

换成国内的源然后就是飞快！- bundle install

遇到的问题

因为之前安装了 concurrent-ruby 1.1.6，而依赖的是1.1.5，还是不能显示Jekyll -v

bundle exec jekyll -v就可以了 – 成功！

此时在Jupyter Book 的目录下运行bundle exec jekyll serve就生成类似GP的Web Book 了！

想要换成中文界面？

前面Jupyter Book 给出的样例，界面默认是 英文的 - 例如 “ON THIS PAGE”，”Book Title (Jupyter Book)”等。想要换成中文界面(“ON THIS PAGE” $\rightarrow$ “本页目录”；”Book Title (Jupyter Book)” $\rightarrow$ “这本书想试试能否使用Jupytrer Book 编纂R算法书”)，就需要修改相应的配置。

Markdown 文件支持中文是没有问题的 - Unicode

其他不做变动，build 和 jekyll serve生成的HTML的中文是没有问题的。

但是，界面信息还是英文：”YOUR BOOK NAME”, “ON THIS PAGE”等。这就需要修改 _config.yml 和 _data目录下的toc.yml。

修改_data目录下的toc.yml - 书籍目录

修改 _config.yml - 但是，jupyter book build时有错误

修改 _config.yml 后 Build出现错误，还要修改jupyter_book的源代码 - utils.py

查了下，是Jupyter Book的 Python代码问题：

  • 找到C:\ProgramData\Anaconda3\Lib\site-packages\jupyter_book目录下的utils.py

  • 然后在对应行的open()函数中添加b即可

之后，build 和 bundle exec jelyll serve 都顺利通过了

通过修改_config.yml和toc.yml可以完成很多配置 - 以后再琢磨吧

组织书籍的章节 - toc.yml

替换相应的图标、logo等 - _config.yml

执行HTML中嵌入代码的的配置 - _config.yml

其他

遗留的需求

要是能使用Jupyter Book 生成PDF就好了。可是，据现有的资料知道，只支持Web 形式的Book。

Jupyter Book 是想模仿国人YiHui XIE 的 R BookDown

https://jupyterbook.org/intro.html

Jupyter Books lets you build an online book using a collection of Jupyter Notebooks and Markdown files. Its output is similar to the excellent Bookdown tool, and adds extra functionality for people running a Jupyter stack.

https://bookdown.org/yihui/bookdown/

https://bookdown.org/yihui/rmarkdown/

https://bookdown.org/yihui/blogdown/

几本Jupyter Book 例子

1. jupyterbook.org自带的样例书，并本地构建

  • 将 book_template拷贝到一个目录，改了名字(目录名字一定不要有空格)。
  • 就直接 jupyter book build xxx [目录名]
  • 有所修改后，再次运行jupyter book build xxx [目录名] --overwrite
  • 进入书籍目录，运行bundle exec jekyll serve

2. 不错的The Riemann Problems for Hyperbolic PDEs - 还有视频

https://github.com/clawpack/riemann_book

JupyterLab，号称极其强大的下一代notebook！- 感兴趣就自己找找吧

一些资料

Dan Toomey 的几本书

  • [Learning Jupyter]
  • [Jupyter Cookbook]
  • [Jupyter for Data Science]

靠，刚发布，就被别人盗取了！

https://www.lizenghai.com/archives/59488.html

喜欢苹果的梨 wechat
敬请关注公众号