How to spreadreST and Sphinx

2012-09-16 Sphinx Con JP 2012(#sphinxconjp)Takanori Suzuki(@takanory)

Who am I(お前誰よ)

• 鈴木 たかのり/ Takanori Suzuki

• Twitter: @takanory

• http://takanory.net/

• PyCon JP 2011, 2012 Staff

• Python mini Hack-a-thon(#pyhack)

• Python Bouldering Club(#kabepy)

Story

• Motivation

• 1st step: reStructuredText

• 2nd step: Plone + reStructuredText

• 3rd step: Sphinx

Motivation

• MS-Word使いたくない / I hate MS-Word

• らくしたい / I hate routine work

• reStructuredTextで書きたい / I like reST

reStructuredText

reStructuredText

• 1st step

• 議事録を書く / Write minutes

• メールに添付 / Attach to email

• なんとなく読める / Readable

reStructuredText

reStructuredText

• reStructuredText がなんとなく読めるようになる / Somehow read

• 同じフォーマットで書く人が出てくる / Followers come out

Plone + reST

Plone + reST

• 2nd step

• 議事録を書く / Write minutes

• サイトにアップ / Site upload

• 週報を書く / Write weekly reports

• 相互に書き込み / Collaboration

Plone + reST

• Plone

• Python based CMS

• reStructuredText format support

Plone + reST

Plone + reST

Plone + reST

• 普段からreSTを使うようになる /

Everyday use reST

• 楽しく書く / Fun writing

• 他の人を真似する / Imitate others

Sphinx

Sphinx

• 3rd step

• チームで資料を書く / Team writing

• 書くことに集中 / Focus on writing

• 設定したい人は使えるようにする /

Installation instructions

チームでドキュメントTeam writing

• Sphinx のファイル構成を全部作る / I

made document structure

• タイトルと担当者をすべて入れる / I fill

in all titles and all authors

• 目次だけできている状態 / Table of

contents completed

書くことに集中Focus on writing

• ファイルはバージョン管理 / use Version

Control System

• サーバでbuildしてみんなが読める /

build on Server

• sphinx環境不要 / Do not need sphinx

使えるようにするInstallation instructions

• インストール手順を書く / Installation

document

• conf.py で環境による条件分岐 /

eliminate environment-dependent

• Windows / Linux / Mac

• blockdiag / seqdiag

Sphinx

• みんなでドキュメントが作れた !! / We

build specification document !!

Summary

• 徐々に広める / little by little spread

• 書くことに集中 / Focus on writing

• 最後は自分で面倒をみる / Take care of

overall

Happy writing!