より長続きするブログ

続けていきたい気持ち。

Sphinxの導入にあたってのメモ書き(for Windows)

概要

会社で使うドキュメントはほとんどがExcelによって生成されていた。

文書作成にWordを使うと、テキストに比べるとバージョン管理しづらく、再利用性に難がある。

簡単なものはMarkdownでガリガリ書き捨てていたけれど、ネストのある箇条書きに番号降るとか、ちょっとレベルの高いレイアウト設定とか、対応しようとするととたんに厳しい。そこでSphinxに白羽の矢が立ったのだった。

Sphinxはテキストで書けるのでGitで管理できるし、再利用もしやすい。インデックス作る機能も標準で備えている。

ここではSphinxのインストール手順と、個人的によく使いそうな設定と、導入したプラグインをまとめて書いた。

なお、インストールは公式手順ほぼまんまなので、Windowsへのインストール — Python製ドキュメンテーションビルダー、Sphinxの日本ユーザ会を読んだ方がいい。

 

 

インストール手順

1. Pythonをインストールする。

SphinxPython上で動くので、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の日本ユーザ会

Python for Windows インストールメモ

etc... (後日更新予定)