Sphinxの導入にあたってのメモ書き(for Windows)
概要
会社で使うドキュメントはほとんどがExcelによって生成されていた。
文書作成にWordを使うと、テキストに比べるとバージョン管理しづらく、再利用性に難がある。
簡単なものはMarkdownでガリガリ書き捨てていたけれど、ネストのある箇条書きに番号降るとか、ちょっとレベルの高いレイアウト設定とか、対応しようとするととたんに厳しい。そこでSphinxに白羽の矢が立ったのだった。
Sphinxはテキストで書けるのでGitで管理できるし、再利用もしやすい。インデックス作る機能も標準で備えている。
ここではSphinxのインストール手順と、個人的によく使いそうな設定と、導入したプラグインをまとめて書いた。
なお、インストールは公式手順ほぼまんまなので、Windowsへのインストール — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会を読んだ方がいい。
インストール手順
1. Pythonをインストールする。
SphinxはPython上で動くので、Pythonのインストールを行う。公式サイトWelcome to Python.org からインストーラーをダウンロードして実行し、指示に従う。バージョン2系と3系があるが、3系を選択するといいと思う。
正しくインストールできたことを確認できる。
python --version
2. Sphinxをインストールする。
pythonのパッケージ管理ツールである、pipを使ってインストールする。
pip install sphinx
3. sphinx-quickstartの確認
Sphinxをインストールすると使えるようになるコマンドの中に、「sphinx-quickstart」というものがある。ドキュメントを作りたいフォルダに移動して、このコマンドを叩く。
mkdir test cd test sphinx-quickstart
対話が始まったらSphinxのインストールに成功している。この対話では色々聞かれる。何とか質問に答え終わると、初期状態のSphinxフォルダができあがるが、詳細は割愛する。
プラグインのインストール
これもpipを使ってインストールする。
pip install pillow blockdiag sphinxcontrib-blockdiag # ブロック図の作成 pip install sphinx-autobuild # ドキュメントのライブリロード pip install sphinx_rtd_theme # 一番気に入っているテーマ(見た目)
設定
source/conf.py
# htmlテーマの変更。 html_theme = 'sphinx_rtd_theme' # Enabled extensions extensions = ['sphinxcontrib.blockdiag'] # Fontpath for blockdiag (truetype font) blockdiag_fontpath = 'C:\Windows\Fonts\meiryo.ttc'
reStructuredTextに関するTips
-
見出しに番号付け
.. toctree:: :numbered:
- ディレクティブを書くときは、改行やインデントをちゃんとしないと、上手く表示できなかったりするので注意
参考URL
Windowsへのインストール — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会
etc... (後日更新予定)