こんにちは。
はけです。

普段はWEBアプリの開発をしており、7年目のSEになります。

Python製のドキュメントビルドツールSphinxって知っていますか？

mdファイルのように テキストベース でドキュメントを作成でき、WEBブラウザで とても見やすい ドキュメントを 自動で 作成してくれます。

「ExcelやWordって装飾とかに時間がとられてなかなか書くことに集中できない！」と感じている方にはとてもおすすめのツールになります！

  • Sphinxを使い始めたい！けど、、どうやってはじめればいいの？
  • まずはSphinxをインストールしたい！

そんな方向けに、本記事ではSphinxのインストール方法を紹介します。

とても簡単にSphinxをインストールし、見やすいドキュメントを作れるようになるのでぜひインストールしてみてください。

WindowsでのSphinxインストール方法

Sphinxのインストール方法は簡単な３STEPです。

  • Pythonのインストール
  • Sphinxのインストール
  • プロジェクトの作成・ビルド

実行環境

実行環境は次の通りです。

  • Windows10
  • VisualStudioCode 1.59.0
  • Python 3.7.9
  • Sphinx 4.0.1

Pythonのインストール

まずはPythonのインストール方法を解説していきます。

なぜPythonかというと、SphinxはPythonで動くツールだからです。
PythonがないとSphinxも動かないのでPythonをインストールする必要があります。

Pythonのインストール方法については次の記事で紹介していますので、Pythonがインストールできていない方は記事を参考にインストールを行ってください。
Pythonのインストール

自分がインストールしたいバージョンのPythonを選択するようにしてください。
特に指定がないかたは最新のPythonを選択しておけば間違いないかと思います。

Sphinxのインストール

Pythonのインストールが完了すると、Sphinxのインストールが始められます。
Sphinxのインストールは次のコマンドで行います。

以降で出てくるコマンドについてはコマンドプロンプトなどのCUIツールで実行してください。
今回はPowerShellで実行したコマンドを紹介しています。
pip install sphinx Pillow

次のコマンドでインストールを確認することができます。

sphinx-quickstart --version

インストールが完了している場合、次のように表示されます。

sphinx-quickstart 4.0.1

プロジェクトの作成

次にプロジェクトを作成します。
プロジェクトとは作成したいドキュメントをまとめたもので、ドキュメントの種類や扱うチームによって分けて作ったりします。

仮にプロジェクト名を「doc」にする場合は、次のコマンドになります。

コマンドを実行した場所にフォルダが作られるので、プロジェクトの情報を保存したい場所まで移動してからコマンドを実行していきます。

cd D:\python
sphinx-quickstart doc

プロジェクト名、著者名（複数可）、プロジェクトの言語はプロジェクトに合った名前をつけてください。

プロジェクトのリリースは何も入力せずにEnterでOKです。

D:\python> sphinx-quickstart doc
Sphinx 4.0.1 クイックスタートユーティリティへようこそ。
以下の設定値を入力してください（Enter キーのみ押した場合、かっこで囲まれた値をデフォルト値として受け入れます）。
選択されたルートパス: doc
Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: 

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

ドキュメントを英語以外の言語で書く場合は、
 言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。
サポートされているコードのリストについては、
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。

> プロジェクトの言語 [en]: ja

ファイル D:\python\doc\conf.py を作成しています。
ファイル D:\python\doc\index.rst を作成しています。
ファイル D:\python\doc\Makefile を作成しています。
ファイル D:\python\doc\make.bat を作成しています。

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

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

D:\python>

一通り完了することでSphinxのインストールが終了となります。
これでSphinxを使用する準備ができました。

次のSTEPではSphinxを使用してHTMLを作る方法を紹介します。
ではさっそく見ていきましょう！

プロジェクトのビルド

先ほど作成したプロジェクトをビルドしてみましょう。
ビルドをすることで、自分が作ったファイル(.rtd)からHTMLファイルを自動で作らせることができます。

次のコマンドで、ビルドできます。

cd doc
.\make.bat html

出力結果が次のようになると成功です。

Sphinx v4.0.1 を実行中
翻訳カタログをロードしています [ja]... 完了
保存された環境データを読み込み中... 完了
ビルド中 [mo]: 更新された 0 件のpoファイル
ビルド中 [html]: 更新された 0 件のソースファイル
環境データを更新中0 件追加, 0 件更新, 0 件削除
更新されたファイルを探しています... 見つかりませんでした
更新が必要な対象はありませんでした
ビルド 成功.
HTMLページは_build\htmlにあります。

成功すると、「doc\_build\html」フォルダの中にHTMLファイルが作られます。
「index.html」をダブルクリックで開いてみるとWEBブラウザ上で画面を見ることができます。

Sphinxのインストール作業は以上になります。
お疲れさまでした。

まとめ

今回の記事ではSphinxのインストール方法について紹介しました。
インストール方法は簡単で、次の３STEPです。
最後のSTEPでは簡単な動作確認まで行っています。

  • Pythonのインストール
  • Sphinxのインストール
  • プロジェクトの作成・ビルド

この記事では書ききれていませんが、Sphinxはとても便利なツールで、
テキストベースでとても見た目がきれいなドキュメントを作ってくれることもそうですが、それ以外にも。。ExcelやWordのように見せ方に時間をかける必要がなく（ゼロではありません）、文章を書くことに集中することができます。

さらに、、、と書いていると長くなってしまうので、これ以降の話は別記事で紹介していきたいと思います。

なにより、今使っていてとても満足しています。
是非みなさんも試してみて、すっきりとしたドキュメントを作りましょう！！