sphinx-quickstartからSphinxの挙動を知る
sphinx-quickstart
https://sphinx-users.jp/gettingstarted/make_project.html を参照する。
cd mkdir sp # ホームディレクトリーが荒れないように、適当なディレクトリーを作る cd sp sphinx-quickstart # y, project_name, author_name, 1.0.0, ja # ディレクトリー build, source と Makefile, make.bat が作られる。2種のメイクは、OS依存なく生成できるように、だろう
index.rst は source ディレクトリーにあった。テキストの先を読んで、手順を前後してみる。
make html # Sphinx で文書が生成される # ファイルマネージャー(pfmanfm)をマウスで実行 # ~/sp/build/html/index.html をマウスで実行。ウェブブラウザー(chromium-browser)で開かれる
さて感想。
- とりあえず何かが作られたと分かった
- サンプルテキストが見えない
- 検索機能がある。Javascriptで構成されている。ユーザーサイドで実行するのか
- ウェブサービスが立っていないので、ラズパイにHTTPアクセスできない。作られた文書を他のコンピューターから参照できない
ページ構成を作っていこう
cd source mousepad index.rst # toctree付近を修正して保存する mousepad expert_python.rst # サンプルテキストを貼り付けて保存する mousepad art_of_community.rst # サンプルテキストを貼り付ける保存する cd .. make html # index.htmlを再読み込みしよう
quickstart から感じたこと、やりたいことの整理
- プロジェクト名でディレクトリーを作ろう
- source をバージョン管理システムに登録する
- バージョン管理システムはHTTPアクセス可能にして、各文書の source を、ブラウザーから編集できるようにする
- 1週に1回程度、source の変化を検査して、current ビルドを建ててしまう
- ビルドエラー、警告が発生したらメールを投げる
- current ビルドをHTTPアクセス可能にする
- リリースビルドは各版、参照できるように残しておく。また、HTTPアクセス可能にする
- リリースビルドでは、印刷用の PDF を出力しよう
- システムのバックアップをどこかに取ろう
- 文書のバックアップをどこかに取ろう
- リリースビルド、current ビルドを手動実行する手段を作ろう
- 版番号を自動採番しよう