くまのためのROOT入門 ／ ROOT for Bearginner
ROOTなどの高エネルギー物理学分野で使っているツールの使い方をまとめているドキュメントです。 もともとは古巣の研究室に設置した ShotakahaDokuWiki（アクセス不可） でまとめていた内容で、 現在は KumaROOT - Read the Docs で公開&更新しています。
僕が研究室に入りROOTを使いはじめたときに、先輩から最初に渡されたのが「猿にも使えるROOT」（通称：さるROOT）でした。 そのタイトルを意識して「くま」にしました。 「さるROOT」の次は「くまROOT」を読んでもらえるように頑張りたいと思います。
想定している読者は、ちょっとだけROOTを使ったことがある学生／研究者です。 パッケージやクラスの網羅的な説明は公式ドキュメントに任せ、 ここでは「〇〇したい」という目的ベースで整理することで、 「逆引き辞典」として使えるものを目指したいと思います。
このドキュメントは以下のプラットフォームで公開しています。
- KumaROOT - Read the Docs（オススメ：最新かつもっとも読みやすい）
- HTML版ダウンロード
- PDF版ダウンロード
- GitHub Pages
Read the Docsは最新のドキュメントが自動的に反映されるようになっています。
このセクションはこのドキュメントを一緒に編集・拡張したい方向けです。 またローカルでビルドしたい方向けです。
$ git clone git@github.com:shotakaha/kumaroot.git
$ cd kumaroot
$ uv sync --all-groups
$ source .venv/bin/activate
$ task docs:serveリポジトリをクローンして、Python環境をセットアップし、task docs:serveを実行すればOKです。
ブラウザでhttp://localhost:8000を開くと、ライブリロード機能付きでドキュメントをプレビューできます。
このドキュメントはSphinxという
Python製のドキュメントビルダーを使用しています。
文書ファイルはreStructuredText（reST）とMarkdown（md）という軽量マークアップ言語を使用しています。
- Git
- Python3.12以上
uv（Pythonパッケージマネージャー）
- リポジトリをクローン
$ git clone git@github.com:shotakaha/kumaroot.git- 依存パッケージをインストール
$ cd kumaroot
$ uv sync --all-groups
$ source .venv/bin/activate$ git switch main
$ git pull
$ git switch -c feature/add-new-guide # 新規ブランチを作成
$ task code # VS Codeを開くdocs/source/ツール名/ツール名-usage.mdにコンテンツの説明を追加docs/source/ツール名/ツール名-<feature>.mdを新規作成ツール名-usage.mdのtoctreeにファイル名を登録- 変更をコミット
$ git add . $ git commit
- GitHubにプッシュしてプルリクエスト（PR）を作成
- 自動テストがパスしたらマージ
コンテンツのファイル名は以下の規則に従います：
docs/source/<category>/<category>-<content>.md
例：
- インデックス（主要）：
root/root-usage.md,python/python-usage.md - インストール方法：
root/root-install.md,python/python-install.md - 機能・使い方：
root/root-th1-fill.md,python/python-pathlib.md - 画像・スクリーンショット：
emacs/fig/mac-key01.png,git/fig/git-status.png
task docs:serve自動的にdocsディレクトリに移動し、ライブリロード機能でドキュメントをプレビュー開始します。
http://localhost:8000でアクセスできます。
# あるターミナルのセッション
task code
# 別のターミナルのセッション
task docs:servetask codeは、常にプロジェクトルートでVS Codeを開くコマンドです。
また、uv環境を引き継ぐことができるので、そのままNotebookやターミナルを開いて作業できます。
task docs:serveは、ドキュメントをライブリロード付きでプレビューするコマンドです。
別のターミナルで実行することを推奨します。
# よく使う
task docs:serve # ライブリロード付きプレビュー
# あまり使わない
task docs:build # 静的HTMLをビルド（docs/build/html/）
task docs:pdf # PDFファイルをビルド（docs/build/latex/）バージョン番号はYYYY.MM.PATCH形式のカレンダーバージョニングを採用しています：
Major (YYYY): 年が変わった時に変更（例：2025.x.x → 2026.x.x）Minor (MM): 月が変わった時に変更（例：2026.3.x → 2026.4.x）Patch: 各コミット（featまたはfix）ごとに自動更新
$ task bump:check # プレビュー（変更なし）
$ task bump:patch # パッチをバンプ（毎回のコミット後）
$ task bump:minor # マイナーをバンプ（月初めに1度）
$ task bump:major # メジャーをバンプ（年初めに1度）使用頻度と説明：
-
task bump:patch（頻繁）：fixまたはfeatコミット後に実行- パッチバージョンを自動更新、
CHANGELOG.mdも自動生成
- パッチバージョンを自動更新、
-
task bump:minor（月1回）：月が変わった際に実行- 例：2026年3月から4月への移行時に実行
-
task bump:major（年1回）：年が変わった際に実行- 例：2026年から2027年への移行時に実行
Pre-commitフックをセットアップすることで、コミット前に自動的にコードをチェックできます：
$ task pre-commit:setup # フックをインストール
$ task pre-commit # 全ファイルをチェック
$ task pre-commit:update # フックを最新に更新Pre-commitフックは以下の検査を実行します：
- Commitizen：コミットメッセージの形式チェック
- Ruff：Pythonコードの形式チェック
- JSON/TOML/YAML/XMLの妥当性チェック
- 末尾の空白・マージコンフリクトの検出
$ task deps:setup # Python環境をセットアップ
$ task deps:check # 更新可能なパッケージを確認
$ task deps:update # パッケージを更新（uv.lockも更新）パッケージを更新した場合は、uv.lockをGitにコミットしてください。
$ task version # 現在のバージョンを表示
$ task status # Gitの状態を表示
$ task log # 最近のコミットを表示（10件）
$ task push # mainブランチをプッシュ詳しい執筆ガイドラインと技術仕様については、CLAUDE.mdを参照してください。 そこには以下の内容が記載されています：
- ドキュメント構造：逆引き形式（目的ベースの整理）の説明
- 日本語スタイル：JTF（Japan Typesetting Foundation）スタイルガイドへの準拠
- Sphinx設定：MyST Parser、タグシステム、etc.
- REST/Markdown 記法：コード例、数式、アドモニション（注釈）の書き方
- ROOT技術リファレンス：C++/Pythonサンプル、メソッドシグネチャの記載方法
MIT License
質問やフィードバックは GitHub Issues でお願いします。