Skip to content

Latest commit

 

History

History
165 lines (117 loc) · 7.94 KB

README.rst

File metadata and controls

165 lines (117 loc) · 7.94 KB

読書ノート

概要

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

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

環境準備

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

作業者に基本的なコマンドライン操作能力を要求する。シェルは Bash を想定。端末で多用するコマンドは次のとおり：

  • make
  • pipenv
  • git

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

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

ローカルコピー作成

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

$ cd $MY_DEV_DIR
$ git clone https://github.com/showa-yojyo/notebook.git
...
$ cd notebook
$ git switch develop
Switched to branch 'develop'
Your branch is up to date with 'origin/develop'.

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

Sphinx 環境作成

まずは Python の仮想環境を作るのが望ましい。Pipenv を用いる場合は次のようにできる：

$ cd doc
$ pipenv install

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

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

執筆

ノートをつづる作業だけならば doc/source 以下にある rst ファイルをテキストエディターで編集し続けていけばよい。 ノート執筆の事前条件として、PC とインターネットアクセス可能であることを挙げる。 GitHub のインターフェイスが優秀なので、モバイル環境でも面倒だができるかもしれないが、 ここでは触れない。

ビルド

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

Pipenv を用いて Sphinx 環境を整えた場合は次のようにビルドする：

$ cd doc
$ pipenv run make html

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

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

成果物配備

原稿を HTML ファイル群に変換して上記 URL に配備することになる。次の二通りの手段がある：

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

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

方法 2. が必要となる状況も考えられるが、この README では言及しない。

ノートを更新するには

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

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

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

一般の方々へ

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

Licensing

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

編集陣および開発陣

プレハブ小屋

当読者ノート責任者。

Contributors

当プロジェクトは個人的な読書・学習ノートであるが、それにもかかわらず、快く貢献、協力、情報提供をいただいたすばらしい GitHub 使用者の一覧を <https://github.com/showa-yojyo/notebook/graphs/contributors> で閲覧可能だ。