Pythonパッケージのドキュメントにチュートリアルを作成する

パッケージには、ユーザが簡単にパッケージを使い始められるようなチュートリアルがあるべきです。 理想的には、チュートリアルは最初から最後まで実行することができ、パッケージのコードベースに対する (テストスイートの上にある) 第二のチェックセットを提供することです。

このページでは、あなたのSphinxドキュメントがビルドされたときに実行される、2つのSphinx拡張機能 (sphinx-gallery と nbsphinx) について紹介します。

ドキュメントのビルド時に実行されるPythonパッケージチュートリアルの作成

よく構成されたチュートリアルをパッケージに加えることで、新しい人があなたのパッケージを使い始めるのが簡単になります。

チュートリアルを簡単にパッケージに追加できるSphinxのツールが2つあります:

• Sphinx Gallery と

• NbSphinx

これらのツールはどちらもSphinxの拡張機能として機能します:

• ユーザーがチュートリアルをサムネイルで見ることができる、Sphinxドキュメントのギャラリータイプのページの作成をサポートしました。

• チュートリアルのコードを実行し、使用するパッケージの "テスト" をもう一段階追加する。

• Pythonコードによるチュートリアルのレンダリングとプロット出力

sphinx gallery:

もしPythonの .py スクリプトを使ってチュートリアルを書きたいのであれば、Sphinx galleryを使うと楽しいでしょう。 Sphinx galleryは、Jupyter Notebookのフォーマットを模倣した、テキストとコードのセクションを持つ .py ファイルを使用します。 ドキュメントをビルドするときは、ギャラリーの拡張子は:

1. 各チュートリアルのコードを実行します。 このようにチュートリアルを実行することで、パッケージの関数、クラス、メソッド、アトリビュート(つまりAPI)が正常に動作しているかどうかを確認することができます。

2. ダウンロード可能なJupyter Notebookの .ipynb ファイルとチュートリアル用の .py スクリプトを作成し、ユーザーがすぐにダウンロードして実行できるようにします。

3. レンダリングされた .html ページを作成し、ユーザーフレンドリーなチュートリアルギャラリーにコード要素とコード出力を表示します。

4. 作成した各チュートリアルのビジュアルサムネイル付きギャラリーランディングページを作成します。

sphinx-gallery は、ユーザーフレンドリーなチュートリアルギャラリーを簡単に作成することができます。 それぞれのチュートリアルにはダウンロードリンクがあり、ユーザーは .py ファイルやJupyter Notebookをダウンロードすることができます。 また、チュートリアルはユーザーフレンドリーなグリッドで表示されます。

下記はsphinx-galleryで作成したチュートリアルの様子です。

sphinx-gallery のチュートリアルは、デフォルトでは、Pythonスクリプト (.py ファイル)とJupyterノートブック (.ipynb ファイル)のダウンロードリンクが下部に含まれています。

Sphinx Galleryの利点

• 簡単にダウンロードできるノートブックと各チュートリアルの .py 出力。

• .pyファイルはGitHubのプルリクエスト環境で簡単に扱えます。

• 素敵なグリッドギャラリーの出力。

• チュートリアルごとのビルド実行時間データ。 例

Sphinx galleryの挑戦

Sphinx galleryを使うことのデメリットは以下の通りです:

• .py ファイルは、特にmatplotlibのプロット出力がある場合、設定に手こずることがあります。

例えば: プロットをレンダリングできるようにするには、各ファイルの先頭に plot_ を付ける必要があります。

• 最近、多くのユーザーはJupyter Notebookで作業することに慣れています。.pyは作業するのに少し使いにくいかもしれません

このようなニュアンスの違いは、潜在的な貢献者があなたのパッケージにチュートリアルを追加することを困難にする可能性があります。 これはまた、メンテナンスの課題でもあります。

ギャラリーのセットアップについて追加します:

$ docs % make html

Sphinx-Gallery successfully executed 2 out of 2 files

ファイルのディレクトリ構造:

tutorials/
    index.rst # landing page for your gallery
    plot_tutorial.py # a tutorial
    plot_tutorial-2.py # a tutorial that produces a plot output
_build/
    build_examples/ # This is where the downloadable tutorial files live
        plot_sample-1.ipynb
        plot_sample-1.py
        ...
    html/
        built_examples/ # You can specify this dir name in gallery settings
            index.html
            plot_sample-1.html
            plot_sample.html
            sg_execution_times.html # in case you want to see build times for each tutorial

nbsphinx - Jupyter Notebooksを使ったチュートリアル

もしチュートリアルを作成するのにJupyter Notebooksを使いたい場合は、nbsphinxを使うことができます。nbsphinxはSphinx galleryと同じように動作します:

• ノートブックを実行し、レンダリングされたチュートリアルの出力を生成します。

• Pro/con デフォルトでは .py と .ipynb ファイルのダウンロードをサポートしていません。 しかし、 conf.pyの設定(epilog settingsを参照)を追加したノートブックへのリンク を追加することができます。

nbsphinx はチュートリアルのギャラリーを作成するために、Sphinx galleryと組み合わせることができます。 しかし、ギャラリーをグリッドとしてレンダリングするのではなく、1つのカラムに全てのギャラリー要素をリストアップします。

tutorials/
    index.md # Landing page for your gallery
    tutorial.ipynb # A tutorial in a jupyter notebook
    another_tutorial.ipynb
# This shows you what the build directory looks like when you build with sphinx-build
_build/
    html/
        # Notice that nbsphinx runs each notebook and produces an
        # html file with all of the outputs of your code
        # you can link to the notebook in your docs by modifying
        # the nbsphinx build - we will cover this in a separate tutorial series focused onPythonpackaging!
        tutorials/
            index.html
            index.md
            plot_sample-2.html
            plot_sample-2.ipynb
            ...