ドキュメント作成ツール

Jupyter Book

概要

Jupyter BookはJupyterノートブックとMarkdownファイルから美しい、発行品質のブックとドキュメントを作成するオープンソースツールです。研究者や教育者が計算的なナラティブを公開するためのデファクトスタンダードとなっています。

詳細

Jupyter Book（ジュピターブック）は2019年にExecutable Booksプロジェクトの一部として開発され、計算科学コンテンツの共有に革命をもたらしました。Sphinx文書エンジンの強力さとJupyterノートブックの対話性を組み合わせ、研究・教育用の高品質な出版物を作成できます。MyST Markdown（Markedly Structured Text）をサポートし、MarkdownでSphinxの全機能を利用できます。JupyterノートブックとMarkdownファイルを統一的に扱い、実行可能なコード、数式、図表、参考文献を含む学術的品質のドキュメントを生成します。2025年現在、14,000以上のオープンなオンライン教科書、ナレッジベース、講義、コース、コミュニティサイトで使用されています。Jupyter Book 2.0では、JupyterHub/Binderを活用した完全にインタラクティブで実行可能な出力、Pyodide/JupyterLiteによるブラウザ内Python実行、リッチなホバープレビュー機能を提供します。MyST-MD文書エンジンを基盤とし、次世代の計算コンテンツ共有ツールとして進化しています。Sphinx-Thebeとの統合により、読者がブラウザ内で直接コードを編集・実行できる機能も提供します。

メリット・デメリット

メリット

• Jupyterノートブック統合: ノートブックとMarkdownの統一的な扱いと実行可能コンテンツ
• 高品質出力: HTML、PDF、ePub等の多様な出版品質フォーマット
• MyST Markdown: MarkdownでSphinxの全機能を利用可能
• インタラクティブ機能: ブラウザ内でのコード実行とライブインタラクション
• Sphinx基盤: 豊富なSphinx拡張機能とテーマシステムの活用
• 学術機能: 数式、引用、交差参照、索引など学術出版に必要な機能
• オープンソース: 無料で商用利用可能、活発なコミュニティサポート

デメリット

• Python依存: PythonとJupyterエコシステムの知識が必要
• 学習コスト: MyST Markdown記法とSphinxの理解に時間が必要
• ビルド時間: 大量のノートブック実行時のビルド時間増加
• 設定の複雑性: 高度なカスタマイズには詳細な設定知識が必要
• バージョン互換性: Jupyter Book 2.0移行に伴う設定変更の必要性
• リソース要求: 大規模プロジェクトでの高いメモリとCPU使用量

主要リンク

• Jupyter Book公式サイト
• Jupyter Book 2.0 ドキュメント
• GitHub リポジトリ
• Executable Books プロジェクト
• MyST Markdown ドキュメント
• Sphinx Book Theme

書き方の例

プロジェクトの初期化

# Jupyter Bookのインストール
pip install jupyter-book

# 新しいブックプロジェクトの作成
jupyter-book create my-book

# プロジェクト構造
my-book/
├── _config.yml           # 設定ファイル
├── _toc.yml             # 目次定義
├── intro.md             # 導入ページ
├── notebooks.ipynb      # サンプルノートブック
├── markdown.md          # Markdownページ
├── markdown-notebooks.md # MarkdownでのJupyterノートブック
└── references.bib       # 参考文献

設定ファイル（_config.yml）

# _config.yml - Jupyter Book設定
title: "計算科学の教科書"
author: "研究者名"
copyright: "2025"
logo: logo.png

# Force re-execution of notebooks on each build
execute:
  execute_notebooks: force

# Define the name of the latex output file for PDF builds
latex:
  latex_documents:
    targetname: book.tex

# Add a bibtex file so that we can create citations
bibtex_bibfiles:
  - references.bib

# Information about where the book exists on the web
repository:
  url: https://github.com/user/my-book
  path_to_book: docs
  branch: main

# Configure your Binder links
launch_buttons:
  notebook_interface: "classic"
  binderhub_url: "https://mybinder.org"
  colab_url: "https://colab.research.google.com"
  jupyterhub_url: "https://datahub.berkeley.edu"
  thebe: true

# Configure Sphinx extensions
sphinx:
  extra_extensions:
    - sphinx_inline_tabs
    - sphinx_proof
    - sphinx_examples
  config:
    html_show_sourcelink: false
    html_js_files:
      - https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js

# HTML-specific settings
html:
  favicon: favicon.ico
  home_page_in_navbar: false
  use_repository_button: true
  use_issues_button: true
  use_edit_page_button: true
  navbar_number_sections: false
  announcement: "📢 この教科書は現在開発中です！"
  google_analytics_id: G-XXXXXXXXXX

# Interact link settings
launch_buttons:
  colab_url: https://colab.research.google.com
  notebook_interface: classic
  binderhub_url: https://mybinder.org
  jupyterhub_url: https://datahub.berkeley.edu
  thebe: true

# Parse and render settings
parse:
  myst_enable_extensions:
    - amsmath
    - colon_fence
    - deflist
    - dollarmath
    - html_image
    - html_admonition
    - linkify
    - replacements
    - smartquotes
    - substitution
    - tasklist
  myst_url_schemes: [mailto, http, https]

目次定義ファイル（_toc.yml）

# _toc.yml - 目次構造
format: jb-book
root: intro
title: 目次

chapters:
- file: chapter1/overview
  title: 第1章：概要
  sections:
  - file: chapter1/introduction
    title: 1.1 はじめに
  - file: chapter1/setup
    title: 1.2 環境設定
    
- file: chapter2/basics
  title: 第2章：基礎
  sections:
  - file: chapter2/theory
    title: 2.1 理論
  - file: chapter2/examples
    title: 2.2 実例
  - file: chapter2/exercises
    title: 2.3 演習問題

- file: notebooks/data-analysis
  title: 第3章：データ分析
  sections:
  - file: notebooks/numpy-tutorial
    title: 3.1 NumPy入門
  - file: notebooks/pandas-tutorial
    title: 3.2 Pandas入門
  - file: notebooks/visualization
    title: 3.3 データ可視化

- file: advanced/index
  title: 第4章：応用
  sections:
  - file: advanced/machine-learning
    title: 4.1 機械学習
  - file: advanced/deep-learning
    title: 4.2 ディープラーニング

- file: references
  title: 参考文献

MyST Markdownの活用

# 計算科学入門

```{epigraph}
すべての科学は計算科学である。

-- John von Neumann

数式とコード

インライン数式

ガウス関数は $f(x) = \frac{1}{\sqrt{2\pi\sigma^2}}e^{-\frac{(x-\mu)^2}{2\sigma^2}}$ で表されます。

ブロック数式

:label: gaussian
f(x) = \frac{1}{\sqrt{2\pi\sigma^2}}e^{-\frac{(x-\mu)^2}{2\sigma^2}}

コードブロック

:tags: [hide-input]

import numpy as np
import matplotlib.pyplot as plt

# ガウス関数の実装
def gaussian(x, mu=0, sigma=1):
    return (1 / np.sqrt(2 * np.pi * sigma**2)) * np.exp(-0.5 * ((x - mu) / sigma)**2)

# プロット
x = np.linspace(-5, 5, 100)
y = gaussian(x)

plt.figure(figsize=(8, 5))
plt.plot(x, y, 'b-', linewidth=2, label='ガウス関数')
plt.xlabel('x')
plt.ylabel('f(x)')
plt.title('ガウス関数のプロット')
plt.legend()
plt.grid(True, alpha=0.3)
plt.show()

アドモニションとボックス

これは重要な注意事項です。

この操作は注意が必要です。

ここで便利なヒントを紹介します。

これは重要な情報です。

実行可能なコンテンツ

:tags: [hide-output]

# インタラクティブな例
import ipywidgets as widgets
from IPython.display import display

def f(x):
    return x ** 2

interactive_plot = widgets.interactive(f, x=10)
display(interactive_plot)

参照と引用

式 {eq}gaussian を参照してください。詳細については {cite}author2023book を参照してください。

プルーフと定理

:label: clt

独立同分布に従う確率変数 $X_1, X_2, \ldots, X_n$ について、
平均 $\mu$、分散 $\sigma^2$ が有限の場合、$n \to \infty$ のとき
標本平均の分布は正規分布に収束する。

証明は省略します。詳細は確率論の教科書を参照してください。

タブとパネル

````{tab-item} Python
```python
def hello():
    print("Hello, Python!")

````{tab-item} R
```r
hello <- function() {
  print("Hello, R!")
}
```

```julia
function hello()
    println("Hello, Julia!")
end
```

## 図表とキャプション

```{figure} images/diagram.png
:height: 300px
:name: system-diagram

システム全体の構成図。この図は重要な概念を視覚的に説明している。

{numref}system-diagram に示すように、システムは3つの主要コンポーネントから構成されています。

### インタラクティブコンテンツの設定

Jupyter Bookでは、Thebeライブラリを使用してブラウザ内でPythonコードを実行できます。

#### 基本設定
```python
# 基本的なインポート
from IPython.display import display, HTML
import ipywidgets as widgets

Thebe設定例

# Thebeの基本設定
def setup_thebe():
    return "Thebe configuration here"

インタラクティブ機能

• ライブコード実行
• ウィジェット表示
• リアルタイムプロット

ビルドとデプロイの自動化

# .github/workflows/deploy-book.yml
name: Build and Deploy Jupyter Book

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: 3.9

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install jupyter-book

      - name: Build the book
        run: |
          jupyter-book build .

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_build/html
          force_orphan: true

開発・ビルドコマンド

# 基本的なビルドコマンド
jupyter-book build my-book/

# クリーンビルド（キャッシュクリア）
jupyter-book clean my-book/
jupyter-book build my-book/

# 特定のページのみビルド
jupyter-book build my-book/ --path-output ./output

# ライブリロード付き開発サーバー
pip install sphinx-autobuild
sphinx-autobuild my-book/_build/html my-book/ --port 8000

# PDF生成
jupyter-book build my-book/ --builder pdflatex

# HTMLとPDFの同時生成
jupyter-book build my-book/ --all

# 実行結果キャッシュの管理
jupyter-book cache clear my-book/
jupyter-book cache show my-book/

# 設定の検証
jupyter-book config sphinx my-book/

# デバッグモード
jupyter-book build my-book/ --verbose

# 並列実行でビルド高速化
jupyter-book build my-book/ -j 4