sphinx ではじめるドキュメント生活 2013 #sphinxconjp

Sphinx ではじめるドキュメント生活 2013

Sphinx-users.jp小宮健

お前だれよ

仕事( 株 ) タイムインターメディア所属テクニカルオフィサ ( 技術責任者 ) として活動

参加コミュニティSphinx-users.jpPython mini hack-a-thon

Sphinx を中心にツールを開発blockdiag シリーズSphinx 拡張機能の開発

Googlechart やカレンダー機能#bookathon 他読書会やってます

Twitter: @tk0miya

アンケート

Sphinx 使っていますか？1. 初めて聞いた2. 名前は聞いたことはある3. インストールはしてみた4. もう使ってるよ

Sphinx ではじめるドキュメント生活 2013

Sphinx-users.jp小宮健

アジェンダ

1. Sphinx について2. Sphinx の現在3. Sphinx の未来4. Sphinx コミュニティの紹介5. まとめ

1.Sphinx について

Sphinx とは？

Georg Brandl 謹製のドキュメントツール

オープンソース (BSD ライセンス )

Sphinx の特徴

テキストから各種フォーマットへの変換HTML, PDF など多くのフォーマットに

対応

Sphinx の特徴

Sphinx の特徴

シンプルなマークアップreST (reSTructured Text)Wiki 記法みたいなもの

目次 (toctree) ベースで文書構造を作る

======見出し======

* 箇条書き* 箇条書き

Sphinx のよいところ

ソースがテキスト形式環境 / エディタを選ばないバージョン管理できるツールで自動生成しやすい

例 ) schema2rst (DB 定義抽出 )機能を拡張することが出来る

Sphinx 拡張やテーマで表現力アップ目次 (toctree) ベースなので文章が書きやすい

Sphinx のいまいちなところ

変換する必要があるreST を書いて make する、の繰り返しツールを使って自動化できるが…

reST は文書レイアウトを表現できない右寄せ、センタリング、二段組などの表現

がない割り切りが必要

画像や図などは別途作る必要があるOffice スイートになれていると、ちょっと

不便 :-(

Sphinx の主な用途

開発ドキュメントPython 等 OSS のドキュメント設計書、マニュアルなど

Web サイトブログ風、コーポレートサイト

出版エキスパート Python プログラミングPython プロフェッショナルプログラミングその他多数

他のツールとの比較

Word◯ 縦書き表記ができる◯ 日本語の文法チェック機能がある◯ 変更履歴の管理がしやすい◯ 画像や図の差し込みが簡単✕ 文書構成をいじるのが大変✕ 複数人で管理するのもやりづらい✕ Office スイートが必要

他のツールとの比較

Excel◯ 誰でも使える。事実上の標準ツール◯ 方眼紙ライクな図、説明が書きやすい✕ 文章構成が存在しない✕ 編集、とくにセルの調整を始めると…✕ 印刷しづらいドキュメントができる✕ Office スイートが必要

他のツールとの比較

Wiki◯ ブラウザだけで編集できる◯ 記法がわかりやすく書きやすい✕ 図や画像は別途作成する必要がある✕ 構成がネットワーク状で迷子になりや

すい✕ 文書レイアウトは指定しづらい ( できな

い )

2.Sphinx の現在

他のツールとの比較

Sphinx-users.jp コンテンツの拡充readthedocs の登場日本語 PDF 環境の整備Sphinx 拡張の増加Sphinx テーマの増加利用事例の増加

Sphinx-users.jp コンテンツの拡充

http://sphinx-users.jp/初心者向けコンテンツTips 集

PDF 出力やテーマ各種拡張の紹介

逆引き辞典イベント情報

readthedocs の登場

Sphinx ドキュメントのホスティングサービス

ドキュメントをビルド、公開してくれるGitHub や BitBucket などにコミット

するだけ文章を書いて公開するのが簡単に

日本語 PDF 環境の整備

日本語 PDF は環境設定が大変だった打田さんの手によって環境が整ってきた

1. Sphinx にパッチを当てる2. TeXLive (2011以降 ) を入れる3. conf.py をいじる4. make latexpdfja を実行する

パッチは本家への取り込みを申請中詳細な手順は sphinx-users.jp で！

Sphinx 拡張の増加

様々なメディアに対応する拡張Youtube, Slideshare, Google Maps

図形を簡単に書くための拡張blockdiag, seqdiag, plantuml

reST を書きやすくする拡張wikitable, japanesesupport

その他テーマ追加、装飾追加 (取り消し線、赤字

など )

Sphinx テーマの増加

theme.core 拡張によりテーマの追加が可能に

スライド系のテーマS6 (sphinxjp.themes.s6)htmlslide (sphinxjp.themes.htmlslide)impressjs

(sphinxjp.themes.impressjs)格好いいテーマ

bizstyle (sphinxjp.themes.bizstyle)Solarized (sphinxjp.themes.solarized)

利用事例の増加

OSS での利用は順調に増加Python 本体、様々なライブラリPython 以外でも利用され始めているSymphony2, CakePHP

伝聞では、業務での利用が増えている社内では HTML で共有PDF に変換して納品

コーポレートサイトに利用されている例も！

3.Sphinx の未来

Sphinx の未来

日本語 PDF のパッチ取り込み標準で PDF が生成できるように次バージョン (1.2) でリリースされる

変換の自動化Jenkins での変換 /公開を簡単にしたい

PDF テーマPDF 出力した時の見栄えを変更したいTeX の知識がなくても変更できるように

Sphinx の未来

テーマや拡張をさらに増やすまだ表現できないものも多い画像など手間のかかるものもある選択肢と自由度を上げていきたい

Sphinx Web エディタブラウザだけで文章を編集したいより Wiki の手軽さに近づけていく

利用事例仕事で使えると幸せになれるはず！

Sphinx の未来

Sphinx を使いはじめるための書籍を書きます

テーマ (候補 )基本的な使い方代表的な拡張の使い方テーマの使い方、作り方その他

4.Sphinx コミュニティの紹介

Sphinx-users.jp

Sphinx コミュニティの運営メーリングリストTwitter (#sphinxjp)

サイトの運営、マニュアルの翻訳イベント開催

Sphinx+翻訳 Hack-a-thon (東京 )Sphinx 朝会 ( 大阪 )Sphinx ハンズオンSphinxCon JP 2012

Sphinx で困ったら…

Sphinx-users.jp に相談してくださいTwitter 、 ML 、イベントなんでも構い

ません質問してみる回答してみる共有する

イベント開催予定

Sphinx+翻訳 Hack-a-thon基本的に毎月開催Connpass にて募集Hack-a-thon スタイル、雑談の場

5. まとめ

まとめ

Sphinx についてSphinx の現在Sphinx の未来Sphinx コミュニティの紹介Sphinx+翻訳 Hack-a-thon 10月もやるよ

Enjoy Documentation!