KumaROOT

くまのためのROOT入門 ／ ROOT for Bearginner

ROOTなどの高エネルギー物理学分野で使っているツールの使い方をまとめているドキュメントです。 もともとは古巣の研究室に設置したShotakahaDokuWiki（アクセス不可）でまとめていた内容で、 現在はKumaROOT - Read the Docsで公開&更新しています。

「くまROOT」：プロジェクト名の由来？

僕が研究室に入りROOTを使いはじめたときに、先輩から最初に渡されたのが「猿にも使えるROOT」（通称：さるROOT）でした。 そのタイトルを意識して「くま」にしました。 「さるROOT」の次は「くまROOT」を読んでもらえるように頑張りたいと思います。

想定している読者は、ちょっとだけROOTを使ったことがある学生／研究者です。 パッケージやクラスの網羅的な説明は公式ドキュメントに任せ、 こでは「〇〇したい」という目的ベースで整理することで、 「逆引き辞典」として使えるものを目指したいと思います。

公開版（Read the Docs）

• HTML
• PDF

Read the Docsで公開する方法

• Read the Docsににログインしてdashboardを開く
• プロジェクトのKumaROOTを選択
• ビルドタブを開く
• ビルドバージョン:をクリックする

個人ページで公開する方法

• make latexpdfしてPDFを作成する
• 作成したPDFをsource/_static/にコピーする
• make htmlしてウェブページを作成する
• リモートサーバーにrsync --delete -auvzでアップロードする

$ poetry run bash deploy.sh

このドキュメントについて

このドキュメントは Sphinxというドキュメト作成ソフトを使っています。 文書本体にはreStructuredText（reST）とMarkdown（md）という軽量マークアップ言語を使っています。

セットアップ

$ git clone git@github.com:shotakaha/kumaroot.git
$ cd kumaroot
$ poetry install --no-root
$ poetry shell

1. GitHubのリポジトリをクローンする
2. poetryを使って依存パッケージをインストールする

新規にコンテンツを作成する場合

$ cd kumaroot
$ git branch ブランチ名
$ git switch ブランチ名
$ code .
// docs/source/ツール名/ツール名-usage.mdを編集する
// docs/source/ツール名/ツール名-コンテンツ名.mdを新規作成する
$ git add 編集したファイル
$ git commit
$ git push
// GitHub上：Pull Requestを作成する
// GitHub上：テストをパスしたら即マージする

1. mainリポジトリからブランチを作成する
2. ツール名/ツール名-usage.mdのtoctreeにファイル名を追加する
3. ツール名/ツール名-コンテンツ名.mdを作成する
4. 変更箇所をgit add & git commit
5. GitHubにgit pushし、プルリクエストを作成する
6. 自動テストをパスしたら即マージする

ライブプレビューする場合

$ cd kumaroot
$ poetry shell
(.venv) $ cd docs
(.venv) $ make livehtml  # 自動でブラウザが開く

1. poetry shellで仮想環境を立ち上げる
2. make livehtmlでライブリロードしながら編集内容を確認する

VS Codeを使ってライブプレビューする場合

$ cd kumaroot
$ code .

1. Poetry設定で virtualenvs.in-project = true が前提
2. KumaROOTのリポジトリでVS Codeを起動する
3. VS Code内でターミナルを開く（command + j）

(.venv) $ cd docs
(.venv) $ make livehtml

3. make livehtmlでライブリロードしながら編集する

バージョン管理

なんとなくセマンティックバージョニングを使おうとしています。

• Major (feat) : 新しい章を追加した場合
• Minor (feat) : 新しい節を追加した場合
• Patch (fix) : 文章を修正した場合

バージョンアップするタイミングは気まぐれです。 とりあえず月1回くらいにしようかな。

依存パッケージの管理

$ poetry export -f requirements.txt --output requirements.txt

Read the Docsでビルドする際に、requirements.txtを使って必要なパッケージを取得しています。 なので、パッケージを更新したらrequirements.txtも更新する必要があります。 poetry exportのサブコマンドで生成し、Gitにコミットします。

ファイルの命名規則

コンテンツのファイル名は、次のような命名規則で管理することにしています。

docs/source/ツール名/ツール名-内容.md

例：ツールのインデックス

ツールのインデックスはツール名/ツール名-usage.mdにします。 このファイルにtoctreeを記載しています。

root/root-usage.md
sphinx/sphinx-usage.md
python/pyhton-usage.md
pandas/pandas-usage.md

例：ツールのインストール方法

ツールのインストール方法はツール名/ツール名-install.mdとしています。

root/root-install.md
sphinx/sphinx-install.md
python/python-install.md
pandas/pandas-install.md

例：ツールの使い方

ツールの使い方は「やりたいこと」を軸にファイルを分けることにします。 とりあえず作成してみて、あとで分割／統合して整理しなおすこともあります。

sphinx/sphinx-theme.md
python/python-pathlib.md
command/command-find.md

例：ツールの説明画像

ごくまれにツールの使い方を説明した画像やスクリーンショットを使っています。 ツールの中にfigとう画像用のディレクトリを作成し、その中で管理するようにしています。

emacs/fig/mac-key01.png
emacs/fig/mac-key02.png
git/fig/git-status.png