nbsanity - 数秒でノートブックを洗練されたWebページとして共有

fastai では、Jupyter Notebooks が技術文書の優れた媒体であるという信念を長く抱いてきました。生コード、可視化、そしてナラティブテキストを単一のドキュメントに統合できるからです。しかし、美しくかつアクセスしやすい形でノートブックを共有することは、常に課題でした。GitHub のノートブックビューアは機能的ですが、適切な技術コミュニケーションに必要な洗練度や機能には欠けています。本日、私たちは nbsanity を発表します。これは、URL を変更するだけで、公開されている GitHub ノートブックを洗練された Web ページに変換するサービスです。

課題

GitHub のレンダリングは機能的ですが、いくつかの制限に悩まされます。レンダリングが遅く、場合によっては完全に失敗することもあります。コードセルを折りたたんだり非表示にしたりする方法がなく、プレゼンテーションのカスタマイズもできません。特に厄介な問題の一つが、コードセルに対する横スクロール機能の欠如であり、全体的に読み込み体験は消費最適化されていません。

Nbviewer はこれらの課題の一部を解決しますが、プレゼンテーションのカスタマイズは許可されません。私たちは以前、fastpages や nbdev などのツールでこれらの課題に対処しましたが、これらのソリューションにはセットアップとメンテナンスが必要です。私たちは、よりシンプルな何かが必要だと気づきました。何のオーバーヘッドもなく即座に共有できるような、解決策です。

私は、Simon Willison の洗練された TIL（Today I Learned）アプローチを発見して以来、技術文書作成のための完璧な低摩擦システムを探し続けてきました。nbsanity によって、ついにそれが実現しました。

nbsanity とは何か？

nbsanity は、GitHub または Gists に公開されている任意の Jupyter ノートブックを、洗練された Web ページとしてレンダリングする無料サービスです。セットアップも設定もデプロイも不要です。

nbsanity は、オープンソースの科学技術出版システムである Quarto によって駆動されています。さまざまなドキュメントツールとの広範な取り組みを通じて、Quarto がノートブックに利用可能な最も人間工学的な静的サイトジェネレーターであることを発見しました。専用拡張機能を通じて Jupyter と VSCode の両方とシームレスに統合されながら、プレゼンテーション、書籍、PDF、Web サイトを含む出力形式において驚くべき柔軟性を提供します。

Quarto の最も強力な機能の一つは、「ディレクティブ」システムです。これは #| で始まる単純なセルコメントであり、コンテンツのレンダリング方法をカスタマイズすることを可能にします。これらのディレクティブは追加が容易で、コードを煩雑にするものではありません。以下に、nbsanity を利用することでアクセスできる Quarto の機能例を示します：

セル可視性制御：#|include: false を使用して特定のセルを実行したまま非表示にできます。

出力管理：#|echo: false で結果のみを表示したり、#|output: asis で生出力を表示したりできます。

エラーハンドリング：#|error: false でエラーメッセージを制御し、#|warning: false で警告を制御できます。

コンテンツの整理： {.panel-tabset} を使用してタブパネルを作成し、 :::{.callout-note} を使用して注釈（これはディレクティブではなく、タブパネルと注釈を作成するマークダウンセル構文です）を追加します。

レイアウト制御： #| fig-width: や #| layout-ncol: などのディレクティブを使用して、カスタム CSS クラスを適用し、図のレイアウトを制御します。

これらのディレクティブに関するドキュメントは、「その他のリソース」セクションにあります。

nbsanity は、一つのことを完璧に行うことに焦点を当てています：パブリックなノートブックを美しくレンダリングすることです。つまり、GitHub または Gist にホストされたノートブックのみで動作します。さらに、ノートブック内の画像にはリモート URL を使用する必要があります。これらの制約により、ユーザーにとってシンプルで高速、かつ完全なメンテナンスフリーのサービスを提供できます。nbsanity は「ノートブックのための Pastebin」と考えてください。GitHub のノートブックから洗練された読み取り体験へと移行する最速の方法です。

さらに愛を込めて追加しました

Quarto のレンダリングプロセスに加え、いくつかの生活の質向上機能を追加しました。レンダリングされたノートブックにはすべて、(1) 目次、(2) 元の GitHub URL へのリンク、(3) コードセル内のテキストの折り返し機能が備わっています。

Simon Willison の shot-scraper を活用して、レンダリングされたノートブックに素敵なソーシャルカードも用意しました：

nbsanity ノートブックのソーシャルカードのテスト https://t.co/5WkGb5dvU6

— Hamel Husain (@HamelHusain) 2024 年 12 月 13 日

これらのソーシャルカードは、ノートブックの実際のコンテンツを表示し、ソーシャルメディア上であなたの投稿を際立たせるのに役立ちます。

始め方

nbsanity を使うのはこれほど簡単です。2 つの方法があります。

オプション 1：URL の変更

GitHub ノートブックの URL 内の github.com を nbsanity.com に置き換えるだけです。これはリポジトリと gists の両方で機能します。例えば：

GitHub URL https://github.com/fastai/lm-hackers/blob/main/lm-hackers.ipynb

nbsanity URL https://nbsanity.com/fastai/lm-hackers/blob/main/lm-hackers.ipynb

gist の場合、URL 形式はわずかに異なります：nbsanity.com/gist/[ユーザー名]/[gist_id] です。詳細についてはこちらの指示をご覧ください。

オプション 2：ブックマークレット

さらに高速に変換するには、このブックマークレットをブックマークバーにドラッグしてください：

imagenbsanity

公開されている GitHub ノートブックを表示している状態でこのブックマークレットをクリックすると、必要な URL の置換が自動的に実行されます。

デモ

Quarto の機能をデモンストレーションするために、お気に入りの機能の一つであるコード折りたたみを見てみましょう。

例 1

展開可能な要約付きでコードセルを折りたたむには、コードセルの上部に以下のディレクティブを追加します：

#| code-fold: true

#| code-summary: "Click to see data preprocessing"

これらのレンダリング指示はこの効果を作成するために使用されますが、読者には表示されません。

クリックしてデータ前処理を表示

import pandas as pd

import numpy as np

サンプルデータの作成

np.random.seed(42)

data = pd.DataFrame({

'id': range(1000),

'value': np.random.normal(0, 1, 1000),

'category': np.random.choice(['A', 'B', 'C'], 1000)

})

プリプロセッシング手順

data['value_normalized'] = (data['value'] - data['value'].mean()) / data['value'].std()

data['value_binned'] = pd.qcut(data['value'], q=5, labels=['Q1', 'Q2', 'Q3', 'Q4', 'Q5'])

例 2

読者がコードを折りたたむオプションを持てるように指定したい場合は、同じ code-fold ディレクティブを使用し、異なるオプションを指定します。

#| code-fold: show

コード

import matplotlib.pyplot as plt

plt.figure(figsize=(8, 4))

plt.plot(np.random.randn(100).cumsum())

plt.title('Random Walk')

plt.show()

重要な注意点

nbsanity はノートブックの共有を容易にしますが、効果的に使用するためにいくつかの重要な点に注意する必要があります。まず、nbsanity はレンダリングサービスのみであり、Quarto ディレクティブで別の指示があったとしても、ノートブックを実行することなく表示するだけです。これにより、潜在的なセキュリティ上の問題が回避されます。

nbsanity にはキャッシュシステムも備わっており、ノートブックのレンダリング履歴を保持します。ノートブックをレンダリングするたびに、その特定のバージョンに対応する一意のリンクが生成されます。その後、ノートブックを更新して再度レンダリングすると、新しいリンクが取得されます。すべての以前のバージョンは、元のリンクを通じて引き続きアクセス可能です。今後導入される新しいレンダリング機能は、新規のレンダリングにのみ適用され、既存の共有済みノートブックは元の外観を維持します。

nbsanity による次のステップ

私たちは、知識共有における摩擦を減らすことが重要だと信じているため、nbsanity を構築しました。2,000 人以上の学生が在籍する「solveit」コースのコミュニティと連携しながら nbsanity を改良し続けており、そこでは学生の作品共有において不可欠な要素となっています。彼らのフィードバックや利用パターンは、私たちが自ら愛用できるようなツールへと磨き上げる手助けとなりました。

使い始める最も良い方法は、実際に試してみることです:

nbsanity.com にアクセスし、ブックマークレットをブラウザのブックマークバーにドラッグしてください

GitHub 上の公開されている Jupyter ノートブックへ移動します

ブックマークレットをクリックして、美しい Quarto レンダリングでノートブックを表示します

「Today I Learned」投稿の作成、技術チュートリアルの共有、プロジェクトドキュメントの強化など、どのような用途でも、このツールがあなたの技術ライティングの旅を少しだけ楽にしてくれることを願っています。本プロジェクトはオープンソースであり GitHub で公開されています。フィードバックや貢献を歓迎します！

P.S. nbsanity を使ってソーシャルメディアでノートブックを共有する際は、私をタグ付けしてください。あなたの作品を見てみたいと思っています！Twitter や LinkedIn で私を見つけられます。

その他のリソース

ノートブック作成時に役立つと私が思う Quarto のドキュメントへのリンクを以下に示します:

cell output: 出力の非表示・表示・フィルタリング、および入力のカスタマイズ

code-display: コードの表示設定（行番号、セル折りたたみ、セル非表示など）

figures: 図の表示方法の設定

tables: テーブルの表示方法の設定

metadata: タイトル、サブタイトル、日付、著者などの設定

numbering: セクション番号の表示切り替え。

脚注

JupyterBook は、ノートブックのプレゼンテーションをカスタマイズできる別のプロジェクトです。fastpages や nbdev、その他の静的サイトジェネレーターと同様に、これらのプロジェクトには非自明なセットアップとメンテナンスが必要です。↩︎

リモート URL を必要とする理由は、関連ファイルを取得する際に GitHub API のレート制限に引っかからないようにするためです。↩︎

サービスは最小限に保つ必要があるため、機能リクエストやプルリクエストについては慎重に対応することをご了承ください。↩︎