Tech Sketch Bucket of Technical Chips by TIS Inc.

Sphinxでドキュメントを作る(インストール編)

Pocket

この記事はeXcale Developer's Blogから移転されたものです。

eXcale開発チームの平栗です。
今回は、Python製のドキュメンテーションビルダーであるSphinxのインストール方法についてご紹介します。

SphinxはreStructuredTextというマークアップ言語でソースを記述するツールで、1つのソースから複数の形式でビルドすることができます。
HTML形式でもビルドできるので、Webブラウザから閲覧できる文書を作成することができます。
Sphinxは日本語の情報が豊富ですので、reStructuredTextが初めての方や、英語が苦手という方でも簡単に使うことができます。
eXcaleの公式ドキュメントでもSphinxを使って作成していますので、Sphinxを使った一例として参考にしていただければと思います。

Pythonをインストールする

Sphinxを使用するにはローカル環境にPythonがインストールされている必要があります。
既にPythonがインストールされている環境をお使いの方は、次のSphinxをインストールするに進んでください。

WindowsやMacをお使いの方は、Pythonの公式サイトまたは日本Pythonユーザ会からインストーラをダウンロードして、インストールしてください。
Linuxをお使いの方は、ディストリビューションのパッケージ管理システムを使ってインストールするか、上記リンクからソースコードをダウンロードしてインストールしてください。
ソースコードからインストールする場合は以下の通りになります。

Sphinxをインストールする

Pythonがインストールできたら、Sphinxの日本ユーザ会が公開しているドキュメントを参考に、ローカル環境にSphinxをインストールします。
本記事ではPythonのeasy_installを利用してインストールします。
easy_installは、setuptoolsというパッケージを導入することで実行可能になります。
setuptoolsはhttps://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.pyをダウンロードし、pythonで実行することで導入できます。
日本ユーザ会のドキュメントでは、古いバージョンのez_setup.pyのリンクが案内されているので、上記のリンクより最新のバージョンを取得するのがよいと思います。
setuptoolsの導入についての詳細は、https://pypi.python.org/pypi/setuptoolsを参照してください。

あとは、easy_installでSphinxをインストールするだけです。

これでSphinxをインストールすることができました。

sphinx-quickstartでドキュメントを作成する

Sphinxを使う環境ができたので早速ローカル環境でドキュメントを作成します。
sphinx-quickstartコマンドをつかってドキュメントを作成していきます。

sphinx-quickstartを実行するとドキュメントの設定について何回か聞かれますので、必要に応じて設定を入れていきます。
sphinx-quickstartを完了した後でも設定を変更することが可能ですので、今回は何も入力せずEnterを押していくだけで構いません。
ただし、ドキュメントのプロジェクト名など入力必須な項目がありますので、これらについては適宜入力してください。
設定の入力が終了すると、下記の内容が出力され、ドキュメントが作成されます。

ドキュメントをHTML形式でビルドする

ドキュメントが作成できたので、正しくできているか確認します。
今回はHTML形式でビルドし、Webブラウザで表示して確認することにします。
HTML形式でビルドするにはmake htmlコマンドを実行します。

上記の内容が出力されたら、_build/html以下にあるindex.htmlをブラウザで表示してみてください。
次の画面が表示されたらドキュメントの作成は成功です。

eXcale_sphinx

最後に

今回は、Sphinxのインストールとsphinx-quickstartを使ったドキュメントの作成についてご紹介しました。
マークアップの仕方など実際のドキュメント作成については、また別の記事でご紹介したいと思います。
今すぐドキュメントを作りたいという方は、Sphinxの日本ユーザ会のサイトにマークアップの仕方について詳しく載っていますので、そちらを参考にドキュメントを作成してみてください。

エンジニア採用中!私たちと一緒に働いてみませんか?