ラズパイにSphinxをインストールする

社内文書の電子化2.0をラズパイで実現したい - sulsnow’s blogの続き。

用意したもの

Raspberry Pi にOSを仕込み、少々の初期設定

  1. Raspberry Pi Imagerでmicro SDカードをFAT32で初期化する
  2. Raspberry Pi Imagerでmicro SDカードにRaspberr Pi OS (32-bit)を書き込む（Ubuntu各種はラズパイが使用不能に追い込まれた）
  3. ラズパイを起動する。ホスト名はraspberrypi。ユーザー名はpi。パスワードは初回起動時に設定する
  4. Raspberry Piの設定を変える。解像度は1280x800。インターフェイスでVNCを有効にする
  5. VNC Viewerでアクセスする。ホスト名でアクセスできないときがあるから、ifconfig |less で調べておく
  6. リポジトリを国内のミラーサイトに変更する。下記資料参照。sudo mousepad /etc/apt/source.list
  7. apt updateする
  8. sudo apt upgradeする
  9. sudo rebootする

Sphinxをインストールする

  1. python3をデフォルトにする。下記資料参照
  2. pip install -U Sphinxする。Sphinxがインストールされる

試行錯誤する

  • 1プロジェクト1文書なのか
  • フォルダ分けやMercurialとの連携はどう考えればいいんだ
  • HTTP公開はどう処置すればいいんだ
  • 分からないことばかりゆえ、MkDocsを試してみたくなった
$ sphinx-quickstart
Sphinx 3.2.1 クイックスタートユーティリティへようこそ。

以下の設定値を入力してください（Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます）。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y

プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: testproject
> 著者名（複数可）: author_name
> プロジェクトのリリース []: 1.0.0

ドキュメントを英語以外の言語で書く場合は、
 言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。

サポートされているコードのリストについては、
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。
> プロジェクトの言語 [en]: ja

ファイル /home/pi/source/conf.py を作成しています。
ファイル /home/pi/source/index.rst を作成しています。
ファイル /home/pi/Makefile を作成しています。
ファイル /home/pi/make.bat を作成しています。

終了：初期ディレクトリ構造が作成されました。

マスターファイル /home/pi/source/index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
 make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck。

資料

source.list

#deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi
# Uncomment line below then 'apt-get update' to enable 'apt-get source'
#deb-src http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi
deb http://ftp.jaist.ac.jp/raspbian stretch main contrib non-free rpi
Raspberry Pi : リポジトリを国内のミラーサイトに変更する | R-Y-O の IT 備忘録 Ver.2.0

python3をデフォルトにする

$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python2.7 1
update-alternatives: /usr/bin/python (python) を提供するために自動モードで /usr/bin/python2.7 を使います
$ sudo update-alternatives --install /usr/bin/python python /usr/bin/python3.7 2
update-alternatives: /usr/bin/python (python) を提供するために自動モードで /usr/bin/python3.7 を使います
Raspberry Pi の Python デフォルトバージョンを 2系 から 3系 に切り替える - Qiita 2019年12月20日に投稿

処置後は、

pi@raspberrypi:~ $ update-alternatives --list python
/usr/bin/python2.7
/usr/bin/python3.7
pi@raspberrypi:~ $ update-alternatives --config python
alternative python (/usr/bin/python を提供) には 2 個の選択肢があります。

  選択肢    パス              優先度  状態
------------------------------------------------------------
* 0            /usr/bin/python3.7   2         自動モード
  1            /usr/bin/python2.7   1         手動モード
  2            /usr/bin/python3.7   2         手動モード

現在の選択 [*] を保持するには <Enter>、さもなければ選択肢の番号のキーを押してください:

とほほのPython入門 - とほほのWWW入門

  • 元々は Python のソースコードに記述された pydoc コメントを整形するツールとして開発されました。
  • 現在では Python ドキュメントに限らず、あらゆるドキュメント作成ツールとしても利用されています。
  • reStructuredText という軽量マークアップ言語を使用します。拡張子は *.rst です。
  • 単一HTML、複数HTML、LaTeX、PDF、プレインテキストなどの出力フォーマットをサポートします。
  • Python プログラムのマニュアル化は、*.py ファイルを *.rst に変換し、これをビルドします。
  • 本ページでは、2019年10月20日時点の最新版 Sphinx 2.2.0 をベースに説明します。
とほほのPython入門 - とほほのWWW入門