sphinxでドキュメントを書こう
TRANSCRIPT
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快適ですよ