Sphinxを使ってみよう

Sphinxを動かしてみる

まず、ドキュメントを作るフォルダを作ります。 そして、そこでコマンドプロンプトを開いてください。 Windows8.1なら、SHIFTキーを押しながらフォルダを右クリックすると、「コマンドウィンドウをここで開く」というメニューが出ます。

そこで

> shpinx-quickstart

と入力します。

すると、ドキュメントの初期設定が始まります。

../_images/sphinx-start-01.png

ドキュメントの初期設定が終わると、こういうファイルができあがってると思います。

../_images/sphinx-start-02.png

そのまま、HTMLファイルを作ってみましょう。

> make html
../_images/sphinx-start-03.png

そうすると、こういうHTMLファイルができあがります。

../_images/sphinx-start-04.png

Hello, worldをやってみる

ドキュメントを作ってみましょう。

まず、index.rstがあるフォルダに、hello.rstというファイルを作ります。 このファイルに、文書の内容を書いていきます。

../_images/sphinx-start-05.png

hello.rstに下記の内容を入力して、上書き保存します。

Get start!
==========

Hello, world.

そして、index.rstを開いて、下記のようにmaxdepthの下にhelloと書いてください。helloは行頭に書かずに、半角スペースを３つ入れてください。

Welcome to Start Sphinx's documentation!
========================================

Contents:

.. toctree::
   :maxdepth: 2

   hello

そして、コマンドプロンプトで

> make html

としてHTMLファイルを作って、_build/html/index.htmlを開いてみると、下図のようになります。

../_images/sphinx-start-06.png

helloというリンクを開くと下図のようになります。

../_images/sphinx-start-07.png

このように、index.rstの中に書いてある

.. toctree::
   :maxdepth: 2

というのは、目次を作るということを意味し、その下に

hello

と書くと、index.rstと同じフォルダにあるhello.rstというファイルを参照するという意味になります。 こうすることで、項目毎にファイルを分けて書くことができます。

日本語で書くときの注意

それでは、日本語で書いてみましょう。 hello.rstの中身を下記のように変えて上書き保存します。

Get start!
==========

こんにちは

そして、コマンドプロンプトで

> make html

としてHTMLファイルを作ってみると、警告がたくさん表示されます。 そして、できあがった_build/html/hello.htmlを表示させると、下図のような読めない文字が表示されていないでしょうか。

../_images/sphinx-start-08.png

これは、hello.rstの文字コードがSJISになっているために起きる現象です。 TeraPadなどの文字コードを指定して保存できるテキストエディタで、UTF-8（UTF-8Nを指定できる場合はUTF-8Nを指定する）で保存してください。 そして、もう一度

> make html

すると、_build/html/hello.htmlをブラウザで表示させると下図のように表示されます。

../_images/sphinx-start-09.png

これは、WindowsとLinuxで日本語の扱い方が異なるために、Linux由来のツールで起きる現象です。