• Home
• コーポレートブログ
• 社内マニュアル整備に活躍中 ドキュメント生成ツールSphinx

前田です。最近Python製のツールにお世話になることが増えてきた気がします。

書籍や社内マニュアルなど大きめの文書を作るときにどんなツールをお使いでしょうか。Wordなどのワープロソフトを使う方が多いかもしれません。当社ではオープンソースのドキュメント生成ツール「Sphinx」を使うことが増えてきました。

Sphinxとは

Sphinxはオープンソースのドキュメント生成ツールです。reST(reStructuredText)と呼ばれる形式で記述したテキストファイルからHTMLやePubなど様々な形式のドキュメントを生成できます。

Sphinxの概要については以下のスライドがわかりやすいです。

利用事例としては Pythonのドキュメント があります。そもそもSphinxは、もともとはPythonのドキュメントを書くために作られたそうです。

拙著「入門Redmine」の執筆は、第3版以降はWordからSphinxに切り替えました。作業のしやすさやツールの扱いやすさにより、効率向上やモチベーション維持に効果があったと感じています。

Sphinxの便利な点

テキスト形式で記述できる

Sphinxで最も便利に感じているのは、reST(reStructuredText)と呼ばれるテキストファイルで原稿を書けることです。テキスト形式ですのでMercurialやGitなどのバージョン管理システムでの更新履歴がやりやすいです。自分が普段使っている、手慣れたテキストエディタで書けるのもうれしいです。

grepやsed などのコマンドラインのテキスト処理用のツールが利用できるのも便利です。例えば用語を統一したいときに、sedを使って複数のテキストファイルを対象にまとめて置換を行うといったこともできます。

テキストファイルなので、フォントの指定など見栄えのための設定を細々と行う必要もありません。見出しや強調など文書の構造を表現するマークアップを行っておけば、Sphinxが自動でスタイルを適用してくれます。文書の見栄えの設定に時間をかけなくてもよいので、内容に注力できます。

読みやすいHTMLが生成される

章や節ごとに分かれた読みやすいHTMLが生成されます。もちろん目次も生成されます。WordやPDFで作ったマニュアルとは異なりwebブラウザで必要なときに簡単に参照できます。目次やページ間のリンクも可能なので、必要な情報を見つけやすいです。

PDFやePubなどにも出力可能

私は普段はHTMLへの出力しか使っていませんが、同じのテキストファイルからPDFやePubにも出力できます。

当社が8月から公開しているオープンソースのリポジトリ管理ツール「Kallithea」の日本語情報サイト kallithea-users.jpは、Sphinxで生成したHTMLをそのまま公開しています。

まとめ

Sphinxを使うと、テキストエディタやバージョン管理システムなど手慣れたツールを使って文書を楽に書くことができます。また、読みやすいHTML形式で出力できるので、会社やチームで共有するのにも便利です。