このリポジトリーは 読書ノート の原稿群だ。Python 製パッケージ Sphinx でビルドするための rst ファイル群で構成している。

この記述は PC 盗難などの事故か何かが私の身に起こって、 ゼロから環境を作らなければならなくなった事態を念頭に置いたものだ。

ノートをつづる作業だけならば rst ファイルをテキストエディターで編集し続けていけばよい。 これらから HTML ファイル群に変換して上記 URL に配備することになる。次の二通りの手段がある：

1. ブランチ master または develop からの git push で起動する GitHub Actions にビルド、配備させる。
2. ローカルでビルドした成果物をブランチ gh-pages にコピーし git push を実行する。

通常は方法 1. で事足りる。これを推奨方法とする。HTML ファイル配備までに必要なすべての処理を、 GitHub が提供するワークフローランナーが実際にこなす。 これはローカルリポジトリーでの git push 実行などの後、だいたい 3, 4 分で完了する。

方法 2. が必要となる状況も考えられるが、この README では言及しない。 次の小工程ごとにビルドまでの手順を以下述べる：

1. 環境準備
2. ローカルコピー作成
3. Sphinx 環境作成

ノート執筆の事前条件として、PC とインターネットアクセス可能であることを挙げる。 GitHub のインターフェイスが優秀なので、モバイル環境でも面倒だができるかもしれないが、 ここでは触れない。

最初にビルド環境と利用ツールを説明する。OS としては Linux あるいはそれに準じる OS での作業を必要とする。Winsows 環境ならば WSL2 が望ましい。それが無理ならば Cygwin や MSYS2 ということになる。 とにかくコンソールだ。試していないが macOS でも行けるのではないだろうか。

作業者に基本的なコマンドライン操作能力を要求する。プロンプトで多用するコマンドは次のとおり：

• bash
• make
• git

とりあえずこれらのコマンドすべてが実行可能であれば、次の工程に移ることができる。 それと、間接的に実行することになる Python が利用可能であることも確認しろ。

コマンド操作を忘れた場合には 入門 bash 読書ノート を確認すること。

次にローカルコピーの作成手順を説明する。コマンドラインから git を用いて GitHub のリモートリポジトリーからファイルをダウンロードする。 仮にゼロからビルド環境を構築するとなると、次のことをすれば最新の状態を再現できる：

bash$ cd $MY_DEV_DIR
bash$ git clone https://github.com/showa-yojyo/notebook.git
bash$ cd notebook
bash$ git switch develop

この説明でわからないのなら Git 利用ノート を確認して欲しい。

まずは Python の仮想環境を作るのが望ましい。

bash$ cd doc
bash$ python -m venv .venv
bash$ pip install -r requirements.txt

これで Sphinx 本体と、本ノートをビルドする際に必要とする拡張モジュール各種が OS またはユーザーの Python 環境か、仮想環境にインストールされる。

このコマンドが何をするのかわからないのなら pip 利用ノート も確認して欲しい。

リポジトリー内のディレクトリー notebook/doc に移動し、コマンド make html を実行するとコマンド sphinx-build が呼び出されて HTML ファイル群が生成される。

bash$ cd doc
bash$ source .venv/activate
bash$ make html
bash$ deactivate

万が一 make 利用不能な場合には、各環境の定める手順でインストールする。 わからない場合には Google で "how to install GNU make" などのキーワードで検索して調べるといい。

ビルドが成功すると、サブディレクトリー notebook/doc/build/html 以下に Sphinx がビルドした成果物のすべてが格納される。

サブディレクトリー notebook/doc/source 以下の拡張子 .rst のファイル群が Sphinx の定める構文に従って記述されたテキストを含む。 これを好きなテキストエディターで開いて編集する。 既存の .rst ファイルを何点か観察することで「ハウスルール」を理解して欲しい。

ブランチ develop から目的に応じてブランチを作成し、そこで作業すること。完了 したら git merge するか、そのまま GitHub 側リポジトリーに git push して管理人が適宜マージする。どちらのマージもオプションは場合により異なる。

master ブランチは年末頃に develop を --squash マージする。タグを付け たりする（ようにする）。

当リポジトリー内の全リソースは私個人が自身のため（だけ）に記したという性質のものだ。 誤字脱字、事実・真実に反する記述、ミスマークアップ等々の報告をいただけると私は個人的に助かりはするのだが、 訂正作業の要望には応じられるとは限らないので、了承願いたい。申し訳ない。

同梱の LICENSE ファイルを参照して欲しい。

• プレハブ小屋: 当読者ノート責任者。
  • Web site: https://github.com/showa-yojyo/notebook
  • E-mail: <yojyo@hotmail.com>
  • Twitter: @showa_yojyo