# 開発コンテナ(Development Containers)の利用 このリポジトリでは [開発コンテナ(Dev Container)](https://containers.dev/)をサポートしています。 これを使うと、ローカルの環境を汚すことなく、RedAmberに必要なツール一式を含んだ環境を準備することができます。この環境には、Ruby、Apache Arrow、RedAmberのソースツリー、GitHub CI、サンプルデータセット、IRubyカーネルを含んだJupyter Labなどが含まれていて、簡単でメンテナンスしやすく、かつ再利用性が高い構成になっています。 RedAmber用のDev Containerは、`.devcontainer` ディレクトリに必要な設定が書かれています。現在の実装では、Dockerfileを使用せず、Dev Containers用のUbuntuベースイメージに、Dev Container Featuresを使って、Python、GitHub CIの環境を加えて作っています。Ruby は Container ができてから走らせるスクリプトでインストールしています。 Dockerfileで作るのと比べて、 - User周りの設定を自動的にやってくれる - 言語環境をFeatureとして個別に追加することができる - PythonではJupyter Labをオプションとして追加できる - Rubyは`rbenv`をインストールしてあって後から別のバージョンを追加できる - Quartoを動かせる環境を簡単に追加でき、Jupyter notebookのソース管理に利用できる 等の利点があります。 ここでは代表的な利用法を2つ紹介します。 ## 1. GitHub Codespacesでクラウド上のVMをブラウザから使う ### 必要なもの GitHubアカウントにサインインしている必要があります。 ### 注意 以下の手順では、Codespacesを起動するあなたのアカウントのクォータを消費します。GitHub Freeに対しては120時間/月・コア(2コアでは60時間)、ストレージ15GB/月が無料で使用できます。使用状況については [Billing and plans](https://github.com/settings/billing)のCodespacesの項を参照してください。 ### 手順 - GitHubの[RedAmberのリポジトリ](https://github.com/red-data-tools/red_amber)を開いてください。 - 開発を行う場合は、フォークしてご自身のリポジトリを作り、それを開いてください。 - リポジトリ内の「<>Code」ボタン、「Codespaces」タブにある、「Create codespace on main」ボタンを押して新しいCodespacesを作成してください。 * 既にCodespacesがある場合は、該当するコンテナ名をクリックすると再接続できます。 - Codespacesの作成には時間がかかります。「View log」をクリックしてぼーっとログを眺めるか、コーヒーを淹れに行くとよいでしょう。 * 今後、GitHub Container Registoryにキャッシュを保存して、速く起動できるようにする予定です。 - VS Code for ブラウザでリポジトリが開きます。 動作の確認は、下の[動作の確認](#動作の確認)を参照してください。 ### 詳細 より詳しくは、[(GitHub Docs)リポジトリの codespace を作成する](https://docs.github.com/ja/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository)を参照してください。 ## 2. ローカルにクローンしたリポジトリ―からDev Containerを立ち上げ、VS Codeで使う ### 必要なもの - Visual Studio Code (October 2020 Release 1.51以降) GitHub Codespaces 拡張機能をインストールして、GitHub 資格情報を使用してサインインする必要があります。[GitHub Docs - GitHub Codespaces - 前提条件](https://docs.github.com/ja/codespaces/developing-in-codespaces/using-github-codespaces-in-visual-studio-code#prerequisites)を参照して設定を済ませておいてください。 - Docker - Windows Windows 10 Pro/Enterprise では Docker Desktop 2.0 以降。 Windows 10 Home (2004+) では、Docker Desktop 2.3 以降と WSL 2 バックエンド。 - Mac Docker Desktop 2.0 以降 - Linux Docker CE/EE 18.06 以降と Docker Compose 1.21 以降 - Git ### 手順 - ローカルに RedAmberリポジトリのクローンを作成します。 - 開発を行う場合は、フォークしてご自身のリポジトリを作り、それをクローンしてください。 ``` $ git clone https://github.com/red-data-toolsまたは貴方のアカウント名/red_amber.git ``` または、GitHub CLIで、 ``` $ gh repo clone red-data-toolsまたは貴方のアカウント名/red_amber ``` とします。 - 作成したローカルのリポジトリフォルダーをVS Codeで開きます。 ``` $ code red_amber ``` - コンテナーで開く 今のフォルダーをコンテナーで再度開きます。 - 左下隅のステータスバーのリモートホスト表示（今はローカルなので「><」の後ろに何もついていない）をクリックするとリモートウィンドウを開くオプションが表示されるので、「コンテナーで再度開く」を選択します。 - コンテナーの構築が開始されます 最初の構築には、数分かかることがあります。それ以降の構築は高速になります。 構築が完了すると、左下隅のステータスバーのリモートホスト表示にコンテナー名が表示されます。 ## 動作の確認 ### ターミナルでインストールされているツールを確認する ターミナルが開いていない場合は、 ``CTRL + ` `` で開いてください。 下記のコマンドを実行して、ツールがインストール済みであることを確かめてください。 ```shell $ ruby -v --jit $ rbenv versions $ gem -v $ gem list $ bundler -v $ iruby -v $ python --version $ pip --version $ pip list $ pipenv --version $ jupyter --version $ jupyter kenelspec list $ git -v $ git config user.name $ gh --version ``` ユーザーは、`vscode` という名前で、`uid/gid` はローカルのユーザーと同じになっています。 ```shell $ id ``` ### RedAmberのテストを走らせてみる ```shell $ bundle exec rake ``` ### REPLでRedAmberを試す プリロードされたデータセットを使って、irbの環境でRedAmberの動作を確認できます。初回はRed Datasetsのデータをロードするため少し時間がかかります。 ```ruby $ rake example (snip) 81: # Welcome to RedAmber example! 82: # This environment will offer these pre-loaded datasets: 83: # penguins, diamonds, iris, starwars, simpsons_paradox_covid, 84: # mtcars, band_members, band_instruments, band_instruments2 85: # import_cars, comecome, rubykaigi, dataframe, subframes => 86: binding.irb irb(main):001:0> ``` irbの動作を途中で止めているので、ここで表示されているデータセットが変数に読み込まれています。 ```ruby irb(main):001:0> import_cars => # Year Audi BMW BMW_MINI Mercedes-Benz VW 0 2017 28336 52527 25427 68221 49040 1 2018 26473 50982 25984 67554 51961 2 2019 24222 46814 23813 66553 46794 3 2020 22304 35712 20196 57041 36576 4 2021 22535 35905 18211 51722 35215 ``` 名前空間の`RedAmber` はインクルードされています。 ```ruby irb(main):002:0> VERSION => "0.5.0" irb(main):003:0> Arrow::VERSION => "12.0.1" ``` `@`を入力すると最初のブレークポイントに戻ることができます。 `exit` を入力するとirbを抜けます。 ### Jupyter LabでRedAmberを試す Python と IRuby カーネルを持ったJupyter Labをブラウザで起動することができます。 ```shell $ rake jupyter ``` で、ローカルの8888ポートでブラウザが立ち上がります。 - Notebookフォルダーとして、`doc/notebook` が割り当てられていて、そこには2つの`.ipynb`ファイルがあります。 - `red_amber.ipynb` : `README.md` で紹介している操作例。 - `examples_of_red_amber.ipynb` : 様々な例を集めたもの。 - `require 'red_amber'` は `lib` 以下のソースを読み込んでいます。 ## Quarto によるドキュメント操作 [Quarto](https://quarto.org/)はオープンソースの科学技術ドキュメントの出版システムです。 この環境では、RedAmber の動作例を活用するために Quarto CLI を使っています。 ```mermaid --- title: Quartoを利用したドキュメント管理 --- flowchart LR id1["Source management (.qmd)"] id2["Analyze and edit by JupyterLab (.ipynb)"] id3["Publish document (.pdf)"] id1 -- convert --> id2 -- convert --> id1 id2 -- render --> id3 id1 -- render --> id3 ``` * Quartoのドキュメント `qmd` 形式でソース管理できます。 * `.qmd`ファイルを Jupyter notebook ファイル(`.ipynb`)に変換して、 Jupyter Lab上で編集したりデータ解析ができます。 * `pdf`形式 に変換することができます。 ### Quarto の動作を確認する Quarto のバージョンと動作環境をチェックするには次のようにします。 ```shell $ quarto -v $ quarto check ``` ヘルプを表示するには下記のようにします。 ```shell $ quarto --help $ quarto render --help ``` ### ソースからJupyter Notebookを生成する `.qmd`ソースファイルから `.ipynb` を生成するには、 ```shell $ bundle exec rake quarto:convert ``` とします。`doc/qmd`フォルダー以下にあるqmdソースファイルから `doc/notebook`フォルダーに`ipynb`ノートブックファイルが作成されます。 より一般的には、 ```shell $ quarto convert ソースファイル.qmd $ quarto convert ソースファイル.qmd --output 出力先ノートブック.ipynb ``` 上の書き方では、出力ファイルはソースファイルの拡張子を `.ipynb`に変えて、ソースファイルと同じディレクトリに保存されます。 下記のコマンドは、Notebookを作成後、Jupyter Labを開きます。 ```shell $ bundle exec rake jupyter ``` ### Jupyter Notebookファイルを`qmd`形式で保存する 編集したJupyter Notebookをqmd形式に変換できます。 ```shell $ quarto convert ノートブック.ipynb $ quarto convert ノートブック.ipynb --output 出力先ソースファイル.qmd ``` ### その他の活用方法 下記のコマンドは`doc/qmd`フォルダー以下にあるqmdソースファイルを`ipynb`に変換し、実行してpdfを作成します。 ```shell $ bundle exec rake quarto:test ``` 下記は`doc/notebook`フォルダーを含めたrakeの生成物を消去します。 ```shell $ rake clean ``` Quartoについてより詳しくは、コマンドラインヘルプ(`quarto --help`)、または[Quarto](https://quarto.org/)公式ページをご覧ください。 ### 謝辞 Quarto の利用は、西田孝三さんの2022年度のRubyアソシエーション開発助成事業プロジェクト『RubyDataエコシステムへのQuartoの導入とその利用の促進のためのコミュニティ活動』 がきっかけとなりました。この場をお借りして感謝申し上げます。