KumaROOT

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

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

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

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

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

公開版（Read the Docs）

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

GitHubのリポジトリをクローンする
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上：テストをパスしたら即マージする

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

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

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

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

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

$ cd kumaroot
$ code .

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

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

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

shotakaha / kumaroot

readme