2024-04-11 | Jupyter Book & Gith

在我们学习某些东西的时候，经常会用pdf、markdown文件或者ipynb文件等去记录一些分析过程，但是如果文件比较多并且比较长的时候，后面查阅起来会很麻烦。因此，想着用Jupyter Book这一工具将他们转成网页书的形式，方便阅读

1 软件安装

# 直接使用pip进行安装就行了
pip install jupyter-book

2 使用

1初始化项目结构

jupyter-book create mybook/

2组织内容

将你的 Jupyter Notebook (.ipynb)、Markdown (.md) 文件以及其他支持的文档放入 mybook/content/ 目录下，一般这个目录自己创建就行了，确保放入前是个空目录

3 配置书本

修改 mybook/_config.yml文件，以配置书本的标题、作者、语言、主题以及其他高级选项。

title: "My R Learning Book"
author: "Lulu Shi"

baseurl: "https://crazzy-rabbit.github.io/Rscript-to-anaylise-and-visualize/"
repository:
   url : "https://github.com/crazzy-rabbit/Rscript-to-anaylise-and-visualize" 

#######################################################################################
sphinx:
  config:
    source_suffix:
      - .ipynb

#######################################################################################
# Execution settings
execute:
  execute_notebooks         : auto  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
  cache                     : ""    # A path to the jupyter cache that will be used to store execution artifacts. Defaults to `_build/.jupyter_cache/`
  exclude_patterns          : []    # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time)
  timeout                   : 30    # The maximum time (in seconds) each notebook cell is allowed to run.
  run_in_temp               : false # If `True`, then a temporary directory will be created and used as the command working directory (cwd),
                                    # otherwise the notebook's parent directory will be the cwd.
  allow_errors              : false # If `False`, when a code cell raises an error the execution is stopped, otherwise all cells are always run.
  stderr_output             : show  # One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe'

修改 mybook/_toc.yml文件，以配置书本的章节

# Table of contents
# Learn more at https://jupyterbook.org/customize/toc.html

format: jb-book
root: intro
chapters:
  - file: "content/R语言学习1-语法函数1-基础介绍.ipynb"
  - file: "content/R语言学习2-语法函数2-数据处理dplyr包.ipynb"
  - file: "content/R语言学习3-语法函数3-正则表达式-stringr包.ipynb"
  - file: "content/R语言学习4-语法函数4-因子型变量_数据框_函数式编程purrr包.ipynb"
  - file: "content/R语言学习5-数据可视化-ggplot入门.ipynb"
  - file: "content/R语言学习6-数据可视化-ggplot进阶(1)之各种图的实现.ipynb"
  - file: "content/R语言学习7-数据可视化-ggplot进阶(2)之标度scale相关语法.ipynb"
  - file: "content/R语言学习8-数据可视化-ggplot进阶(3)之主题设置theme语法.ipynb"
  - file: "content/R语言学习9-数据可视化-ggplot进阶(4)之图例系统.ipynb"
  - file: "content/R语言学习10-数据可视化-ggplot进阶(5)之扩展内容.ipynb"
  - file: "content/R语言学习11-数据可视化-ggplot进阶(6)之统计图层.ipynb"

5 构建书本

jupyter-book build -W -n --keep-going --all .

# .表示当前目录为mybook/
# --all表示重新构建所有

生成的文件在_build/文件夹下，而发布书时，只需要_build/html文件夹下的内容

6 发布到Github Pages

_build/html 目录下的内容（不包括这个目录本身）上传到 GitHub 新建的reposiory中，点击settings，后选择pages，然后进行分支的选择（如果是新建的reposiory，则选择main\root）

注意！！！在 main\root目录下需要添加.nojekyll 文件空文件:

• 由于 GitHub Pages 默认使用 Jekyll 来构建网站，
• 而 Jupyter Book 生成的静态网站可能不符合 Jekyll 的要求，
• 因此需要在 分支的根目录下添加一个名为 .nojekyll 的空文件。这样可以告诉 GitHub Pages 不要使用 Jekyll 来构建您的网站。