https://pycon.jp/2015/ja/schedule/presentation/6/
オープンソースのドキュメンテーションツール、Sphinxを用いたドキュメント作成について紹介します。Sphinxは文章を構造化しやすいため、分かりやすく、美しいドキュメントを簡単に作ることが出来ます。SphinxはHTML, ePub, PDFなどの複数のドキュメント形式を出力し、ドキュメントはreStructuredText(reST)記法で記載します。 「触ってみようと逡巡している人」や「使おうと思ったけどよく分からない」といった方を対象に、基本的な文法、ビルド、についてハンズオン形式で学んでいきます。
用意するもの
- Sphinxをインストールする環境
- OSはWindows, Mac, Ubuntu いずれか
- Pythonをインストールしておいてください（Python2でも3でもOK）
- Sphinx-1.3以降のインストール
当日の進め方
- 講師が研修資料を用意し、プロジェクターに研修資料を映しながら説明していきます。
- 各自手元のPCで入力し実行結果を確認します。 質問は随時回答致します。
ハンズオン内容
- Sphinx のインストール
- Sphinx-quickstart を実行する
- ビルドしてみる（HTML）
- 基礎的なマークアップを書いて変換してみる：セクション、箇条書き、太字、斜体、リンク、code-block、テーブル、画像、複数のファイルをリンク(toctree)
- Sphinx リファレンスの読み方
- わからなくなったときの助けの呼び方
対象者
- Sphinxでドキュメントを作成したい方。
- ドキュメントを楽しく作りたい方。
- 既にSphinxを使っているけれど、わからないことがある方
- ロジカルなドキュメントを書きたい方
参加者へのお願い
- 事前に Sphinx のインストールをお願いします。インストール方法は http://sphinx-users.jp/gettingstarted/index.html に掲載されています。
- インストールをしていない方向けの説明も行いますが、インストールが済んでいるとハンズオンで実践できる内容が多くなります。（会場にインターネット回線があるか不明なため、事前にご用意お願いします）
- 既にSphinxを使っている方は、わからないことや困っていることなどをまとめておくと、当日質問しやすいかと思います。
参考資料
- Sphinx をはじめよう (Sphinx-users.jp) http://sphinx-users.jp/gettingstarted/index.html
- オープンソースカンファレンス 2013 Tokyo/Spring の際のハンズオン資料 http://usaturn.net/osc/