Jupyter Book 使用与配置指南

10.2. Jupyter Book 使用与配置指南#

10.2.1. 项目目录结构及介绍#

Jupyter Book 的目录结构如下：

.
├── binder
│   └── environment.yml  #Binder 集成环境配置
├── docs  # 文档源代码存放位置
├── examples  # 示例内容
├── jupyter_book  # Jupyter Book 核心库代码
├── scripts  # 自定义脚本
├── tests  # 测试用例
├── .gitignore  # Git 忽略规则
├── .pre-commit-config.yaml  # Pre-commit 配置
├── .readthedocs.yml  # ReadTheDocs 构建配置
├── CHANGELOG.md  # 更新日志
├── LICENSE  # 许可证文件
├── README.md  # 项目简介
├── codecov.yml  # Codecov 代码覆盖率配置
├── conftest.py  # Pytest 配置
└── pyproject.toml  # Python 项目配置

  1. binder: 这个目录包含了用于创建 Binder 环境的文件，比如 environment.yml 文件，它描述了运行 Jupyter Book 所需的依赖。

  2. docs: 存放书的内容，通常是 Markdown 文件或 Jupyter 笔记本。

  3. examples: 提供示例内容，帮助用户了解 Jupyter Book 功能。

  4. jupyter_book: 包含 Jupyter Book 库的源代码。

  5. scripts: 可能包含一些辅助脚本，用于自动化任务。

  6. tests: 测试代码，确保项目功能正常。

  7. .gitignore, .pre-commit-config.yaml, .readthedocs.yml 和其他配置文件用于版本控制、代码质量检查以及文档构建。

项目启动文件介绍

Jupyter Book 的主要命令行接口是通过 jb 命令行工具实现的。要构建或管理你的书籍，你需要在终端中运行以下命令：

构建书籍：

jb build <your_book_directory>

这将从指定目录下的源文件构建一个静态网站和可选的 PDF 输出。

清理输出：

jb clean <your_book_directory>

清除书籍的构建输出，以便重新开始。

查看书籍：

jb serve <your_book_directory>

启动本地服务器，实时预览书籍内容变化。

创建书籍：

jb init

初始化一个新的 Jupyter Book 项目模板。

这些命令位于 jupyter-book 目录中的 Python 脚本中，通过调用 python -m jupyter_book 来执行。

项目的配置文件介绍

Jupyter Book 使用 YAML 格式的配置文件来定制书籍的构建过程。默认情况下，配置文件位于你的书籍根目录下，名为 _config.yml。下面是一些基本的配置选项：

  1. book_filename: 书籍的主页面文件名，默认为 index.md。

  2. language_code: 书籍使用的语言代码，默认为 en（英语）。

  3. use_mathjax: 是否启用 MathJax 显示数学公式，默认为 true。

  4. html_theme: HTML 输出的主题，例如 'sphinx_rtd_theme' 或 'alabaster'。

  5. pdf_engine: 创建 PDF 输出时使用的引擎，如 pdflatex 或 weasyprint。

你可以在 _config.yml 中添加更多自定义设置，比如添加额外的 CSS 风格，定义自定义的 TOC（目录），或者控制书籍构建的其他方面。对于完整的配置选项列表，建议查阅 Jupyter Book 官方文档。

请注意，如果你没有 _config.yml 文件，你可以通过运行 jb init 命令来创建一个基础配置文件模板。

目录