---
title: JupyterとSphinxで本書いた
lang: ja-jp
tags: IT, event, sphinx
description: SphinxCon JP 2019
slideOptions:
# spotlight:
# enabled: true
allottedMinutes: 20 # Minutes alloted for a slide.
parallaxBackgroundImage: 'https://www.sphinx-doc.org/ja/master/_static/headerbg.png'
---

# JupyterとSphinxで本書いた

SphinxCon JP 2019
2019-11-25@株式会社インターネットイニシアティブ

driller@patraqushe

---

## 誰？

- どりらん
- [@patraqushe](https://twitter.com/patraqushe) 
- フラフラしてます
- 最近よく歩いてます<a href="https://www.dragonquest.jp/walk/"><img src="https://pbs.twimg.com/profile_images/1169446429720363008/EAQDTMsd.png" width=35 height=35></a>

----

## SphinxCon JP 2017でやったLTの続きです

<iframe width="640" height="480" allowfullscreen frameborder=0 src="https://slideship.com/embed/presentations/GX5q8tJTPHuctnT1LeAZZd/"></iframe>

----

### 木星から帰ってきました

[](https://dic.nicovideo.jp/a/ジュピトリス)

---

## さいしょに書いた本

[](https://gihyo.jp/book/2017/978-4-7741-9223-9)

----

## どうやって書いたか

原稿はAsciiDoc

- Jupyterのコードを貼り付け
- Jupyterの実行結果を貼り付け

----

## 課題

- コードと結果の移植がちょーめんどくさい
- 転記漏れで出力と結果が異なる事件が発生
- レビュー時に発覚して事なきを得た
- 変更するときも大変

----

## どうするべきだったか？

執筆者内の反省会にて

**全部Jupyterで書けばよかった**

----

## Jupyterでドキュメントを書く利点

解説、コード、実行結果が一元化できる

----

### 一元化すると...

コードや結果を転記する必要がなくなる

----

### 転記する必要がなくなると...

- 転記漏れ・ミスがなくなる
- テストやチェックがドキュメント上(Jupyter)から行える

----

こういうのを防げる


---

## どうやって書くのか

- Jupyter上に全部書く
- 解説部分はMarkdownやreSTで書く
- コードはJupyter上で実行する
- ドキュメントビルダでHTML化やPDF化
- Jupyterに対応したドキュメントビルダ

----

### Jupyterで書いた雑誌

[](https://gihyo.jp/magazine/SD/archive/2018/201802) [](https://gihyo.jp/book/2019/978-4-297-10396-5)

----

### Jupyterで書いた書籍

2冊を執筆中 :books:


----

## Jupyterをビルドできるライブラリ

- Sphinx
- nbsphinx
- jupyter-sphinx
- jupyter-book
- Nikola
- Miyadaiku

---

### [nbsphinx](https://nbsphinx.readthedocs.io/)

- Sphinxのextension
- HTMLやLaTeXに変換できる
- 基本的な使い方はSphinxと同じ

----

### nbsphinxでドキュメントを作る手順

----

#### インストール

pip install jupyter nbsphinx

----

#### プロジェクトを作成

sphinx-quickstart -q -p nbsample -a nbauther -l ja --sep

----

##### source/conf.py

下記を追記

extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
]
exclude_patterns = ['_build', '**.ipynb_checkpoints']

----

#### Jupyter原稿を書く

`source/sample.ipynb`


----

##### Jupyter NotebookでreSTセルにする方法


----

##### JupyterLabでreSTセルにする方法


----

#### toctreeにNotebookを追加

拡張子は含めない

`source/index.rst`

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   sample

----

#### ビルド

make html


----

サンプルプロジェクト

https://github.com/drillan/SphinxConJP2019

---

## はまったり工夫したこと

Jupyterに関連したTipsなど

----

### 実行結果がJavaScriptだとレンダリングされない

- Bokeh
- Plotly
- etc

[Jupyter Sphinx](https://jupyter-sphinx.readthedocs.io/en/latest/)（後述）を入れたら解決した
なぜかは不明

----

#### 特定のセルをドキュメントの対象外としたい

コード実行時に生成されてしまうファイルを削除する処理など

!rm tempfile

セルのmetadataに下記を入れておくとビルドの対象外にできる

"nbsphinx": "hidden"

Hidden Cells: https://nbsphinx.readthedocs.io/en/0.5.0/hidden-cells.html

----

### コーディングスタイルを統一したい

Jupyter Notebook
- [jupyter-black](https://github.com/drillan/jupyter-black)

JupyterLab
- [jupyterlab_code_formatter](https://github.com/ryantam626/jupyterlab_code_formatter)

----

### 日本語のチェックをしたい :crossed_flags:

- [textlint](https://textlint.github.io)
- [textlint-plugin-rst](https://github.com/jimo1001/textlint-plugin-rst)
- reStructuredText
- [textlint-rule-preset-ja-technical-writing](https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing)
- 技術文書向けのtextlintルールプリセット
- [preset-jtf-style](https://github.com/textlint-ja/textlint-rule-preset-JTF-style)
- JTF日本語標準スタイルガイドのtextlint版
- [textlint-rule-prh](https://github.com/textlint-rule/textlint-rule-prh)
- 表記ゆれ校正
- [WEB+DB_PRESS.yml](https://github.com/prh/rules/blob/master/media/WEB%2BDB_PRESS.yml)
- WEB+DB PRESSのルール

----

#### どうやってJupyterのファイルをtextlintにかけるか

- [nbconvert](https://nbconvert.readthedocs.io/en/latest/)を使う
- MarkdownやreSTのセルだけ抜き出せる

ipynbファイルをtextlintにするための魔法のコマンド

jupyter nbconvert xxx.ipynb \
  --to rst --stdout \
  --TemplateExporter.exclude_code_cell=True | \
  textlint --stdin

----

#### nbformat

[nbformat](https://nbformat.readthedocs.io/en/latest/)を使うと色々できる

<iframe width="460" height="284" allowfullscreen frameborder=0 src="https://slideship.com/embed/presentations/QqQrVw7nF6Vfwh9ivh2RJX/"></iframe>

----

### Notebookのdiffをしたい

[nbdime](https://nbdime.readthedocs.io/en/latest/)が超便利


----

#### [Notebook Extensions](https://nbdime.readthedocs.io/en/latest/extensions.html)

ボタン一発でdiffができる


---

## はまったり工夫したこと

Jupyter関係なくSphinxに関連したこと

----

### 黒丸数字がlatexでビルドできない

[#6841](https://github.com/sphinx-doc/sphinx/pull/6841)で解決


----

### Font Awesomeを使いたい

<i class="fa-step-forward fa"></i> のようなアイコンをだしたい

----

##### [sphinx fontawesome](https://github.com/fraoustin/sphinx_fontawesome)

ディレクティブとロールを使って書ける

ディレクティブ

.. fa:: check

ロール

:fa:`check`
:fa:`check lg`
:fa:`square-o`

----

### SVGの画像を表に埋め込みたい


----

#### replaceが便利

参考: [replaceを使ってテーブルに画像を貼る](https://sphinx-users.jp/reverse-dict/table/replace-table.html)

.. |Zoom| raw:: html

   <svg viewBox="0 0 1000 1000" class="icon" height="1em" width="1em"><path d="m1000-25l-250 251c40 63 63 138 63 218 0 224-182 406-407 406-224 0-406-182-406-406s183-406 407-406c80 0 155 22 218 62l250-250 125 125z m-812 250l0 438 437 0 0-438-437 0z m62 375l313 0 0-312-313 0 0 312z" transform="matrix(1 0 0 -1 0 850)"></path></svg>
   
.. list-table:: モードバーの機能
   :widths: 10 25 65
   :header-rows: 1
   :name: mode_bar_list

   * - アイコン
     - ボタン名
     - 機能
   * - |Zoom|
     - Zoom
     - マウスドラッグでグラフ領域を拡大します。元のビューに戻るには、プロット上の任意の場所をダブルクリックします。

----

#### ビルド環境を共有したい :whale:

[Docker Image](https://hub.docker.com/repository/docker/driller/nbsphinx-build)を作った

HTMLでビルド

docker run --rm -v <project_dir>:/build driller/nbsphinx-build make html

latexでビルド

docker run --rm -v <project_dir>:/build driller/nbsphinx-build make latexpdf

Imageを`driller/nbsphinx-build:requirements`にすると`requirements.txt`のパッケージをインストールしてからビルド

---

## 課題

- JavaScriptの出力がlatexに変換できない


- CIでビルド
- GitHub Actionsを使ってやりたかった
- [ためしてみたい](https://github.com/ammaraskar/sphinx-action)

---

## オマケ: [Jupyter Sphinx](https://jupyter-sphinx.readthedocs.io/en/latest/)

- reST上に書いたコードをJupyterのカーネルで実行できる
- nbsphinxはipynbで記述するのに対してJupyter SphinxはreSTで記述
- コードと実行結果がドキュメント化できる
- [ThebeLab](https://thebelab.readthedocs.io/en/latest/)に対応

----

### Jupyter Sphinxの書き方

コードブロックを`jupyter-execute`ディレクティブにするとJupyterで実行される

.. jupyter-execute::

  name = 'world'
  print('hello ' + name + '!')

---

## 謝辞

- Sphinxメンテナの皆様
- Sphinx users jpの皆様
- Python ドキュメント日本語訳プロジェクトの皆様