Tech Sketch Bucket of Technical Chips by TIS Inc.

Sphinxでドキュメントを作る (マークアップ編)

Pocket

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

eXcale開発チームの平栗です。
前回のSphinxでドキュメントを作る(インストール編)から時間が空いてしまいましたが、今回はSphinxでドキュメントをマークアップについてご紹介します。

前回もご紹介しましたが、SphinxはreStructuredTextというマークアップ言語でソースを記述するツールで、1つのソースから複数の形式にビルドできるツールです。
Sphinxでは、reStructuredTextの記述方法を知らないとドキュメントを作成できませんが、reStructuredTextはソースの記述がシンプルでかつ可読性が高いので、初めての方でも簡単にソースを作成することができます。

ドキュメントのひな形を作成する

早速ドキュメントを作成していきましょう。
まずはsphinx-quickstartでドキュメントのひな形を作成します。
sphinx-quickstartの使い方については、前回の記事を参考にしてください。

ドキュメントの内容を記述する

ドキュメントのひな形ができたので、実際に内容を記述していきます。
今回は、記述済みのソースから実際にドキュメントをビルドして、ソースと作成したドキュメントを見比べることでソースの記述方法についてご紹介したいと思います。
早速、プロジェクトのトップディレクトリに下記のファイルを作成してみてください。

ソースのマークアップが終わったので、ビルドして作成したドキュメントを確認します。
今回はHTML形式でビルドするので、プロジェクトのトップディレクトリで下記のコマンドを実行します。

ビルドが成功したら、_build/html以下にあるindex.htmlをWebブラウザで表示し、コンテンツの一覧にあるリンクをクリックしてみてください。
以下の画面が表示されればドキュメントの作成は成功です。

ドキュメントが作成できたので、簡単にソースを見ていきましょう。
まずは「Sphinxでドキュメント作成」や「マークアップ」などの見出しの文字列についてですが、上記のソースでは文字列を=や#といった記号で上下を囲ったり下線を引いています。
このように記述すると、Sphinxが記号で囲まれている文字列を見出しであると解釈します。
太字や斜体についても、*で文字列を囲むことでフォントスタイルが変更されます。
また、トップページにはコンテンツの一覧を表示するtoctreeを使い、他のページのファイル名を並べて記述することで、他のページに含まれるコンテンツへのリンクを生成しています。
マークアップについては他にも表を作成したり、画像を挿入したりと様々な種類があり、複雑な記述をすることなく綺麗なドキュメントの作成が可能です。
マークアップに関する詳細はSphinxの日本ユーザ会のサイトをご覧ください。

補足:Sphinxを1.2にバージョンアップする

12/10にSphinxのバージョン1.2が公開されています。
1.2では、HTML形式でビルドした場合、widthやheightでサイズ変更されている画像にリンクが貼られ、クリックするとフルサイズで画像が表示されるようになっています。
Sphinxを1.2にバージョンアップするには、Python Package IndexからSphinx-1.2-py2.7.eggをダウンロードし、easy_installでインストールします。

これでSphinxを1.2にバージョンアップすることができます。

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