個人的ドキュメンテーションツールトップ100

Sphinx-Users.JP
ウサターン長谷川
#ssmjp 2015/10/16

自己紹介
某社
Web広告配信会社のインフラエンジニア
 好きなポートセキュリティ上の問題があるので公表は差し控えさせて頂きま
す
 好きなGUIアプリあふｗ
 好きなCLIアプリ awk
Python系の勉強会に出没してます。
2
Twitter: usaturn

Sphinx-Users.JP
「Sphinx」というPythonのドキュメンテーション
ツールのユーザ会で活動しています。
3
現在、@togakushiさん他、
ユーザ会のメンバで
SoftwareDesignにSphinx
の記事を連載中！

今回のテーマ
ドキュメントを書くツールはこの世の
中に星の数ほどあります。
 Microsoftの「Word」や「Excel方眼紙」
 LibreOfficeの「Writer」
 Wikiクローン「PukiWiki」「MediaWiki」
個人的に「これは！」と思われるドキュメンテーショ
ンツールのトップ100をご紹介したいと思います。

第100位
 Pythonのリファレンス作成ツール
「Sphinx」

Pythonのリファレンス作成ツール「Sphinx」
 Pythonのリファレンスを書く為のツールとして作ら
れたツール
※もちろんPython製
 Web上では色々なドキュメントがSphinxで公開され
ている

第99位
 プレーンテキストで書く
「Sphinx」

プレーンテキストで書く「Sphinx」
 プレーンテキストである事でさまざまな恩恵を受け
られます。
 視認性の良いreStructuredTextで書ける
 好きなテキストエディタで編集できる
 EmacsとVimどちらでも好きなエディタが使えます。
 それぞれのエディタでSphinx用の拡張が存在します。
 バージョン管理が容易
 差分を比較しやすい

第98位
 手軽にHTMLが作成できる
「Sphinx」

手軽にHTMLが作成できる「Sphinx」
 make html というコマンドを打つだけで見やすい
htmlができる
 CI環境で、リポジトリにプッシュ → make → Web
サイトの更新
 GithubやBitbucketなどのリポジトリを登録してお
くだけでプッシュすると自動的に更新される
Readthedocs

第97位
 さまざまなフォーマットに変換する
「Sphinx」

さまざまなフォーマットに変換する「Sphinx」
 html以外にもLaTeX、pdf、man、Windowsヘルプ
などに変換する事ができる
 あるマークアップ形式で書かれた文書を別の形式へ
変換する「pandoc」というツールを使って
Markdown文書やhtmlをreStructuredTextに変換す
る裏技もある

第96位
 ドキュメントを育てやすい
「Sphinx」

ドキュメントを育てやすい「Sphinx」
 ドキュメントを構造化しやすい
 セクション
 toctree
 自由にリンクを作成
 索引
 doc（別のreST文書へのリンク）
 ref（ラベルへのリンク）

第95位
 本を執筆する時には
「Sphinx」

本を執筆する時には「Sphinx」
続きはWebで
http://sphinx-users.jp/book_usage.html

第94位
 活発な日本人メンテナがいる
「Sphinx」

Sphinxメンテナ
Takayuki Shimizukawa
@shimizukawa
Sphinxの共同メンテナ (2011-)
PyCon JP 2014 会計
共著書・共訳書
Sphinxをはじめよう (2013)
Pythonプロフェッショナルプログラミング
(2012)
エキスパートPythonプログラミング
(2010)

第1位
 ドキュメントを作りたくなってしまう魔法のツール
「Sphinx」

ドキュメントを作りたくなってしまう魔法のツール「Sphinx」
 セクションやtoctreeを使ってあらかじめドキュメン
トの骨格だけを作っておき、気が向いた部分を書い
いたり、穴埋めのように足りない部分を書き足した
り気まぐれにドキュメントを作成する事ができるの
でいつの間にかドキュメントが増え、ドキュメント
が書くのが楽しくなっていくとゆーか、調子が乗っ
てくると半ば義務感に駆られてドキュメントの量が
増えていくとゆー体験ができます。

以上
ご清聴ありがとうございました

個人的ドキュメンテーションツールトップ100

More Related Content

What's hot (20)

Similar to 個人的ドキュメンテーションツールトップ100 (20)

More from Go Yamada (6)