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 をバージョン管理システムに登録する
  • 1週に1回程度、source の変化を検査して、current ビルドを建ててしまう
    • ビルドエラー、警告が発生したらメールを投げる
  • current ビルドをHTTPアクセス可能にする
  • リリースビルドは各版、参照できるように残しておく。また、HTTPアクセス可能にする
  • リリースビルドでは、印刷用の PDF を出力しよう
  • システムのバックアップをどこかに取ろう
  • 文書のバックアップをどこかに取ろう
  • リリースビルド、current ビルドを手動実行する手段を作ろう
  • 版番号を自動採番しよう