ドキュメントを書きたくなってしまう魔法のツール Sphinx 入門

概要

オープンソースのドキュメンテーションツール、Sphinxを用いたドキュメント作成について紹介します。Sphinxは分かりやすく、美しいドキュメントを簡単に作ることが出来ます。SphinxはHTML, ePub, PDFなどの複数のドキュメント形式を出力し、ドキュメントはreStructuredText(reST)記法で記載します。「触ってみようと逡巡している人」や「使おうと思ったけどよく分からない」といった方を対象に、基本的な文法、ビルド、についてハンズオン形式で学んでいきます。

Sphinx とは

Sphinx はオープンソースのドキュメンテーションツールです。 reST(reStructuredText) や Markdown で書かれたドキュメントを HTML, ePub, PDF などの複数のドキュメント形式に変換できます。

対象者

Sphinx でドキュメントを作成したい方
Sphinx を使い始めようとして挫折している方
既に Sphinx を使っているけれど、わからないことがある方
ドキュメント作成ツール(Microsoft Word、Microsoft Excel、Wikiクローン)を使っているけど物足りない方

System Message: WARNING/2 (<string>, line 23)

Bullet list ends without a blank line; unexpected unindent.

表計算ソフトでの複雑なドキュメント作成に泣かされている方

用意するもの

Sphinx をインストールした環境(ノートパソコン)
- OS は Windows, Mac, Linux系いずれかのうち使い慣れているもの
- Python は 2.7 系か 3.4 以上を使って Sphinx をインストールして下さい
- Sphinx は 1.6 以降を推奨します

当日の進め方

講師が研修資料を用意し、プロジェクターに研修資料を映しながら説明していきます。
各自用意してきたノートパソコンで入力し実行結果を確認します。質問は随時回答致します。

ハンズオン内容

プロジェクトの作成 (sphinx-quickstart)
HTML をビルドしてみる（make html）
基礎的なマークアップ(reST, ディレクティブ)を書いてビルドしてみる
- セクション
- 箇条書き
- 太字
- 斜体
- リンク
- code-block
- テーブル
- 画像
- 複数のファイルをリンク(toctree)
Markdown を使う際の注意
Sphinx リファレンスの読み方
わからなくなったときの助けの呼び方

参加者へのお願い

事前に Sphinx のインストールをお願いします。
- http://sphinx-users.jp/gettingstarted/index.html に手順が掲載されています。
- わからないことがあった場合、Connpass のコメント欄や Twitter( #sphinxjp タグ付き)などで質問していただけるとサポート可能です。
既に Sphinx を使っている方は、わからないことや困っていることなどをまとめておくと、当日質問しやすいかと思います。