sphinxでドキュメントを書こう

Sphinxでドキュメントを 書こう @kzfm

Sphinx •  文書作成ツール •  http://sphinx-doc.org/ (本家) – http://sphinx-users.jp/ (日本語)

•  ReSTで書いて出力 – html,docx,pdf,epub – 多数のフォーマット対応

HTMLに変換

h"p://www.kzfmix.com/flaski/

epub -> mobi -> kindle

INSTALL & QUICK START

install & quick start $  mkvirtualenv  sphinxtest  (virtualenvで使う時)  $  pip  install  sphinx  

#  quick-‐‑‒start  

$  mkdir  testdoc;  cd  testdoc  $  sphinx-‐‑‒quickstart  Welcome  to  the  Sphinx  1.2b1  quickstart  utility.  

###  質問に答えていくとひな形ができる  ###  

Enter  the  root  path  for  documentation.  >  Root  path  for  the  documentation  [.]:  

出来たひな形 $  tree  .  ├──  Makefile  ├──  _̲build  ├──  _̲static  ├──  _̲templates  ├──  conf.py  ├──  index.rst  └──  make.bat  

3  directories,  4  files  

rstファイルを追加してmake [html,epub,etc]でドキュメント作成

TIPSとか

MSWord

•  sphinx-docxbuilderエクステンション – サラリーマンの必需品

$  mkdir  exts  $  cd  exts/  $  hg  clone  https://bitbucket.org/haraisao/sphinx-‐‑‒docxbuilder  

epub -> mobi •  現状Sphinxだけでは難しそうなのでepubをmobiに変換している

•  kindlegen (amazon製) –  http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211

•  calibre –  http://calibre-ebook.com/

Emacs ReST-mode 便利なキーバインドがたくさんあるよ

GitHubでSphinxを使う 1. gh-pagesというブランチを作る 2. sphinxtogithubというエクステンショ

ンを入れる 3. Sphinxで文章を書く 4. make htmlする 5. cp -pr _build/html/* ./でビルドされた

htmlをカレントディレクトリに移動する 6. commitしてpushすると公開できるよう

になる

例）ゆるふわHaskell

三島Haskell無名関数の会では、 一緒にHaskellを学ぶそこのあなたを お待ちしています

デプロイ •  Makefileに書く

•  fabricを使う – わからないことは@ando_ando_ando先生に聞こう！（お気軽に）

更新検知 -> make -> browser reload

•  python-livereloadを使おう – https://github.com/lepture/python-livereload

•  Sphinx と LiveReload を組み合わせる – http://kshigeru.blogspot.jp/2013/02/sphinx-livereload.html

demo

まとめ

Sphinx快適ですよ