Sphinx執筆環境をWindowsに構築する手順

この記事はWindowsにてSphinxによるドキュメントを執筆する環境構築の手順を記載します。
Sphinxを利用するプロジェクトに新規メンバーが増えた際に説明が必要となったため書いた記事です。
基本的な文法などはユーザーグループサイトに記載がありますので、本記事では割愛します。

Sphinxとは

reStructuredText形式で記述した文章をHTMLやePub、PDF（LaTeX経由）へ出力できる素敵なツールです。
Pythonのドキュメントを作成するために作られたツールのため、Pythonで動作します。

詳細は日本のSphinxユーザグループにより和訳されたオフィシャルページを確認しましょう。
http://www.sphinx-doc.org/ja/stable/index.html

なにがいいの？

例えば、Wordと比較すると以下のようなメリットがあります。

• 文章を記述する際に見た目を気にする労力を減らせる
• テキストベースで管理できるので、リポジトリ管理や変更点の確認が容易に
• 構造化された体系的なドキュメントを作成するための仕組みが整っている（toctreeなど）

でもお高いんでしょう？

もちろんデメリットもあります。

• reStructuredTextの記法を覚える必要がある
• 記述した結果を確認するためにPythonの環境が必要になる
• 使い捨てる文章を書くためには大がかりになってしまう

このため、製品のマニュアルやドキュメントなど、比較的量が多く長期間にわたって維持・メンテナンスを行う文章を記述する際に適しているツールです。

今回私は、自社製品のユーザー向けマニュアルを大幅に改版するプロジェクトにて、Word文書からSphinxへの移行を選択しました。この記事はそれに伴う環境構築の手順を共有するものです。

Sphinx執筆環境をWindowsに構築する

Minicondaの導入

まず、Windows上でPythonが動作する環境を構築します。
最近のPython環境構築ではAnacondaという様々なパッケージを含んだオールインワンのプラットフォームが多く使われ、こちらにSphinxも含まれています。
ただし、今回のように目的が明確な環境構築では不要なパッケージが非常に多くインストールされてしまいます。
このため必要最小限なパッケージが含まれているMinicondaを利用します。

1. Minicondaのサイトよりインストーラ（Python3.6 Window用64bit）をダウンロードする。

2. インストーラを起動する。
   

3. ライセンス確認が表示されるので"I Agree"。
   

4. インストール対象のユーザー選択。今回は"All Users"を選択する。
   

5. インストール先ディレクトリの指定。パスに日本語が含まれないように注意。
   

6. 「PATHに追加するか」「Miniconda環境をPC標準のPython環境として登録するか」を選択する。
   今回は新規に構築したWindows上に環境を作成しているため、PATHの追加も行ってしまう。
   （既存環境で構築する場合は環境を破壊しないように注意）
   

7. インストールを行い完了まで見届ける。
   
   

8. 動作確認
   コマンドプロンプトよりバージョンを確認するコマンドを実行し値が表示されることを確認する。

conda -V
conda 4.3.27

python --version
Python 3.6.2 :: Anaconda, Inc.

Sphinxの導入

※仮想環境を利用する場合は下記のコマンドで環境作成後、activateにより仮想環境に入ります。

conda create -n [環境名] python=[バージョン番号] anaconda

conda install [パッケージ名]にてパッケージのインストールを行います。
Sphinxのバージョン指定が必要な場合は[パッケージ名]=[バージョン]の記載で指定します。
Sphinx1.7.xでは、既存のプラグイン側動作しない事例があったため、その場合は1.6.6などを指定すると無難です。

conda install Sphinx


Fetching package metadata .............
Solving package specifications: .

Package plan for installation in environment C:\ProgramData\Miniconda3:

The following NEW packages will be INSTALLED:

    alabaster:                0.7.10-py36hcd07829_0
    babel:                    2.5.0-py36h35444c1_0
    docutils:                 0.14-py36h6012d8f_0
    imagesize:                0.7.1-py36he29f638_0
    jinja2:                   2.9.6-py36h10aa3a0_1
    markupsafe:               1.0-py36h0e26971_1
    pygments:                 2.2.0-py36hb010967_0
    pytz:                     2017.2-py36h05d413f_1
    snowballstemmer:          1.2.1-py36h763602f_0
    sphinx:                   1.6.3-py36h9bb690b_0
    sphinxcontrib:            1.0-py36hbbac3d2_1
    sphinxcontrib-websupport: 1.0.1-py36hb5e5916_1
    typing:                   3.6.2-py36hb035bda_0

Proceed ([y]/n)?

インストールができたら必要に応じて追加のパッケージ（プラグイン）を導入しましょう。
個人的なおすすめは以下のものです。

プラグイン紹介

conda install プラグイン名 または pip insatall プラグイン名にてインストールを行います。

sphinx-autobuild
ドキュメントが保存されたタイミングで自動的にビルド、ブラウザの更新を行ってくれる。
参照：sphinx-autobuildで再ビルド、ブラウザの再リロードの手間を省いてSphinx文書をサクサク作成

Windowsの場合 make.bat に livehtml の定義を記述します。

if "%1" == "livehtml" (
        %SPHINXBUILD% -p 8000 -b html %SOURCEDIR% %BUILDDIR%/html
        sphinx-autobuild -p 8000 -b html %SOURCEDIR% %BUILDDIR%/html
        if errorlevel 1 exit /b 1
        goto end
)

make livehtmlを実行すると、ソースディレクトリを監視し変更時（ファイル保存時）に自動ビルドが走ります。
ビルド結果は、localhost:8000にて確認することができます。

sphinxcontrib-actdiag
sphinxcontrib-blockdiag
sphinxcontrib-nwdiag
sphinxcontrib-seqdiag

ブロック図、シーケンス図などを生成することができる。プロジェクトで使う用途の図に応じて導入する。
参照：Sphinxでblockdiagを使って簡単にシーケンス図、ブロック図を含めたHTMLベースのドキュメントを生成する環境を整える

エディタを整える

UTF-8に対応したエディタであればAtomでもVSCodeでも秀丸でもサクラエディタでも問題ありません。
ただし素のエディタでrst形式のテキストを記述するのは結構大変です。プラグインを導入して便利にしましょう。

例えば、サクラエディタでは、SakuraEditorTypeRestというシンタックスハイライトのテンプレートを作成してくださった方がいらっしゃいます。ありがたく利用しましょう。

書き始める

これまでの手順でrstファイルを書き、Sphinxでビルドし閲覧できる環境ができました。
はじめてSphinxドキュメントを書く場合は、下記のユーザーグループのページに丁寧なチュートリアルがあります。
http://sphinx-users.jp/gettingstarted/make_project.html

書き方をマスターし素敵なSphinxライフを送りましょう！！

Sphinxのバージョン管理やCIについては別記事で改めて記載します。