KumaROOT

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

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

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

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

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

公開版（Read the Docs）

• HTML
• PDF
• GitHub Pages

Read the Docsで公開する方法

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

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

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

$ uv run bash deploy.sh

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

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

セットアップ

$ git clone git@github.com:shotakaha/kumaroot.git
$ cd kumaroot
$ uv sync --all-extras
$ source .venv/bin/activate

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

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

$ 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. 自動テストをパスしたら即マージする

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

task docs:serve

task docs:serveは自動的にdocsディレクトリに移動し、ライブリロードでドキュメントのプレビューを開始します。

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

$ task code

task codeはVS Codeを起動します。 VS Code内でターミナルを開き（command + j）、task docs:serveを実行してライブプレビューを開始できます。

ドキュメントビルドタスク

task docs:serve      # Preview docs locally with live reload
task docs:build      # Build docs as static HTML
task docs:pdf        # Build docs as PDF

バージョン管理

バージョン番号は カレンダーバージョニングと セマンティックバージョニングを 組み合わせて使うことにしました。

• Major : 年
• Minor : 月
• Patch (feat / fix) : 文章を修正した場合

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

バージョン管理タスク

task bump:check

次のバージョンバンプをプレビューします。実際には変更を行いません。

task bump:patch

変更がある程度貯まったらパッチバージョンを更新してください。 バージョンバンプ時にCHANGELOG.mdが自動的に更新されます。

task bump:minor

毎月1度、マイナーバージョンを更新してください。 バージョンバンプ時にCHANGELOG.mdが自動的に更新されます。

task bump:major

毎年、メジャーバージョンを更新してください。 通常は年が変わるときに実行します。

Pre-commitフック

task pre-commit:setup

task pre-commit:setupでpre-commitフックをインストールします。

task pre-commit

task pre-commitで全ファイルに対してpre-commitフックを実行します。

task pre-commit:update

task pre-commit:updateでpre-commitフックを最新バージョンに更新できます。

依存パッケージの管理

task deps:setup

task deps:setupでPython環境をセットアップできます。

task deps:check

task deps:checkで更新が利用可能な依存パッケージを確認できます。

task deps:update

task deps:updateで依存パッケージを更新できます。 更新されたuv.lockをGitにコミットしてください。

ファイルの命名規則

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

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

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

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

root/root-usage.md
sphinx/sphinx-usage.md
python/python-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