18. BPstudy#64 ドキュメントを作りたくなってしまう魔法のツール Sphinx 2012年版

18.1. #bpstudy 発表メモ

• Sphinxってどんな物？
• Sphinxを使ってみよう！
• 既存のドキュメンテーションツールとの比較
• 利用例 http://sphinx-users.jp/example.html

18.2. Sphinxってどんな物？

ソースコードをプレーンテキストで作成するドキュメンテーションツール ソースコードから色々なフォーマットに出力する事が可能 reStructuredTextという記法でソースコードを作成

reStructuredText(reST)という、Wikiに似た記法でマークアップをしていきます。

18.3. 出力フォーマット

html latex pdf json htmlhelp epub text man .......etc

18.4. Sphinxを使ってみよう！

SphinxのインストールからreStructuredText基礎まで、適宜デモを交えて

インストールから、実際にドキュメントを作成していく所までをご説明します。

プレーンテキストである為に、バージョン管理しやすい -> 複数人で編集しやすい！ toctreeにより階層構造を促され、文書作成が横道にそれにくい 文書の分割、結合が楽 さまざまな拡張があり、拡張を自身で作成する事も可能

• pdf化
• プラグイン

reSTは行指向のフォーマットであるため、差分もみやすくなっています。

18.5. 既存のドキュメンテーションツールとの比較

• Excel
• Word
• Wiki

18.6. 利用例

• Sphinxを利用しているサイト
• 弊社利用事例

18.7. wiki

初めに構成を決めて階層構造を作っていくような形にしないと、後々 いわゆるwikiネームがある為、リンク切れを起こしにくい

基本的にWebサーバが必要

18.8. word

18.9. excel

18.10. Sphinx

wikiに似ている。

• Sphinxをこんな風に使ってます
  • 利用例 (ドキュメント、サイト構築、設計書、ビジネスユース)
  • 弊社の事例
  • 利用事例のデモ

弱い所 番号 表 ブラウザ

しょうこうせい

用途自体に被るところが大きい、あるいは似ているならばSphinxを選んでみるのも手でしょう

一番ストレスフリーなのではないか？

ドキュメントの体裁を気にしすぎて作成作業が進まない。 オートコレクトや自動インデントの機能が余計に働いて困る。 ドキュメントが比較しにくい。 ドキュメントを分割して構造化するのが難しい。 同一ファイルを複数人が並行作業しつつ変更するのが難しい。 ドキュメントの一部を抜き出して新たなドキュメントを作成するのが難しい。