WindowsのVSCodeでsphinxドキュメントを作るために必要な最低限の設定3選

こんにちは。
はけです。

普段はWEBアプリの開発をしており、7年目のSEになります。
Sphinxを使用するときに、どのように環境をつくればよいか悩むことはないでしょうか。

Sphinxを使いはじめたけど、どんな設定が最適か知りたい！
VScode上でSphinxを簡単につくる環境を整えたい！

そんな方向けに！本記事ではわたしが普段使っていて、最低限必要だ！ と思う設定をまとめて紹介します
エディタはVisualStudioCode(VSCode)を使用しています。
VSCodeはとても動作が軽くカスタマイズがしやすい上に高機能なので愛用しています。

私はSphinxを使用し始めて半年ほどですが、今回紹介する方法で、ストレスを感じることなく、さくさくドキュメントの作成を進めることができています。

ぜひ皆様も同じ環境を作って快適にドキュメント作成をしてみてください！

なぜSphinx？

ちなみにSphinxを知らない方向けに、、、Sphinxがどういうものかを簡単に紹介しておきます。Sphinxは、次のような特徴があります。

Excelなどのようにバイナリファイルではなく、テキストファイル でドキュメントをつくる。
作ったテキストファイルからHTML/PDF/epubなどの 見やすい形式に自動で変換 してくれる
ファイル内のリンクで 別のファイルを呼び出すことができる （ファイルを階層的に管理できる）

私が一番気にいっているのは、テキストを書くことに集中できることです。
Wordなどはどうしてもドキュメントのデザインに時間がかかってしまい、ちょっとした修正でも結果的に10分/15分など時間がかかってしまいます。
その点、Sphinxでは文章を書くことに集中することができます。

装飾内容についてSphinxではmdやrestructedTextなどの形式でテキストで表します。
そのため装飾に全く時間をかけなくていいかというとそうではありません。
ただし、ルールさえ覚えてしまえばテキストなので一瞬で装飾をすることができます。
テキストで表すため、他の箇所の文言や装飾を再現するのも一瞬です。

sphinxでドキュメントを作るために必要な最低限の設定3選

私がSphinxを使ってドキュメントを作る際に必ず設定すべきなのは次の３つです。

テーマの設定
ハイライト設定
自動ビルドの設定

さらにあればいいなと思うものとして次の設定があります。
今回は最低限の設定に絞って解説し、さらにあればいいと思う設定については別の記事で紹介しようと思います。

UML作成ツールの導入
Markdownを使用するための設定
Todoの使用設定

Sphinxのインストールがまだだよ！という方は下のリンクでSphinxのインストール方法を解説していますのでまずはSphinxのインストールからはじめてください。
WindowsでのSphinxインストール方法

Sphinxで設定を変えるときは、設定ファイルの中の設定を書き換えます。
その設定ファイルがSphinxプロジェクト作成時にできる「conf.py」になります。
次からの設定変更時も基本的に「conf.py」を編集します。

実行環境

Windows10
VisualStudioCode 1.59.0
Python 3.7.9
Sphinx 4.0.1

テーマの設定

まずはSphinxのテーマを変えます。

テーマとはドキュメントのデザインのことで、テーマを変えることで自分の好きな見た目のドキュメントにすることができます。テーマはカスタマイズすることもできますが、WEBデザインの知識が必要ですのですでにあるテンプレートを使用した方が楽です。

私のお気に入りは「sphinx_rtd_theme」というテーマになります。
こんな感じです。

テーマの選定

次のリンクのようにテーマをまとめてくれているところがありますので、自分の好きなテーマを探してみてください。
スフィンクスのテーマギャラリー

次からの手順は「sphinx_rtd_theme」を使用する場合の手順になりますが、ほとんどのテーマが同じ手順になると思います。
テーマごとの設定手順は各テーマのWEBページに載っていると思いますのでそこを参照してください。

テーマのインストール

Sphinxに標準で存在するテーマはインストールがいりませんが、「sphinx_rtd_theme」は標準ではないのでインストールから行います。
コマンドプロンプトからpipでインストールしていきます。

pip install sphinx-rtd-theme

テーマの設定変更

次にインストールしたテーマを設定します。
「conf.py」のhtml_themeを先ほどの「sphinx_rtd_theme」に変更します。

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
# 
html_theme = 'sphinx_rtd_theme'

これでテーマ変更が完了です！

ハイライト設定

SphinxではrestructedTextという書き方を採用しています。
restructedTextで書いたときに、次の画像のように書いた内容を意味ごとに色付けして見やすくしてくれるのがハイライトです。
ハイライトがあるだけでテキストの見やすさが格段に上がります。

このハイライト設定もVSCodeのプラグインを使うことで簡単に設定することができます。

restructedTextのインストール

「拡張機能」→「reStructuredText」を検索→「インストール」でインストールすることができます。

インストールするプラグインは次の２つです。

reStructuredText
Extension Pack for reStructuredText

これで「.rst」拡張子のファイルはハイライト表示してくれます。

自動ビルドの設定

この自動ビルドの設定はテキストファイルを編集しながら、リアルタイムに出来上がったHTMLを確認できるということです。
この設定をしないと、WEBページをみたいと思ったタイミングで毎回「HTMLをつくる」作業が必要になります。
その作業を自動化するための手順になります。

自動ビルド用のライブラリインストール

自動ビルドを行ってくれる「sphinx-autobuild」をインストールします。
コマンドプロンプトで次のコマンドを実行します。

pip install sphinx-autobuild

バッチファイルの修正

先ほどインストールしたライブラリを動かすには「sphinx-autobuild doc doc/_build/html」とコマンドを打つ必要がありますが、このコマンドを毎回打つのは大変です。

そのためその作業も簡単にできるように「make.bat」を編集します。

「Makefile」や「make.bat」があると思いますが、Windowsなのでバッチファイルを編集します。Linuxなどで動かすときは「Makefile」を使用しましょう。

次の2点を変更してください。

if “%1” == “livehtml” goto livehtml

REM この1行を追加
if "%1" == "livehtml" goto livehtml
if "%1" == "" goto help

追加する場所に注意してください。

sphinx-autobuildコマンド

%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
REM 次の3行を追加
:livehtml:
sphinx-autobuild %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end

追加する場所に注意してください。

自動ビルドの実行

これで、ターミナル上から自動ビルド用のコマンドを実行することができます。
プロジェクト名がdocの場合次のようなコマンドになります。

cd doc
.\make.bat livehtml

プロジェクト内のbatファイルの場所に移動し、batを実行しています。
実行すると次のようなメッセージが出ますので、Ctrlを押しながらURL部分をクリックするとWEB上で見ることができます。

[I 211114 14:41:17 server:335] Serving on http://127.0.0.1:8000

これでテキストファイルを編集してみてください。
リアルタイムに編集内容を見ることができます！！

まとめ

最後まで読んでいただきありがとうございます。
この記事ではSphinxドキュメントを作るために必要な最低限の設定として次の３つの手順を紹介しました。

テーマの設定
ハイライト設定
自動ビルドの設定

また、さらに設定するといいものとして次の３点を別の記事で紹介します。

UML作成ツールの導入
Markdownを使用するための設定
Todoの使用設定

記事ができ次第、リンクを貼る予定です。

私もSphinxを始めたときに、どんな設定がいいんだろう？設定方法ってどうすればいいんだろう？と悩みながら試行錯誤したので、そんな方の助けになればとこの記事を書くことにしました。
そんな方に喜んでもらえると幸いです。