社内マニュアル整備に活躍中 ドキュメント生成ツールSphinx

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

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

Sphinxとは

Copyright © 2007-2015 by the Sphinx team

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

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

ドキュメントを作りたくなってしまう魔法のツールSphinx from Takayuki Shimizukawa

利用事例としては 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形式で出力できるので、会社やチームで共有するのにも便利です。

ファーエンドテクノロジーからのお知らせ(2024/02/28更新)
2024年3月16日 オライリー本の全冊公開日のお知らせ(もくもく勉強会も同時開催)
ファーエンドテクノロジーが所蔵するオライリー本(全冊)公開日のご案内です。公開日には「もくもく勉強会」も同時開催します。
My Redmine スタンダードプランおよびAdminサポートデスクプランの料金改定のお知らせ【2024年4月ご利用分より】
2024年4月ご利用分より、My Redmine スタンダードプラン(民間企業・個人向け及び官公庁向け)とAdminサポートデスクプランの料金を改定いたします。
My Subversion 一部のプラン・料金改定のお知らせ【2024年4月ご利用分より】
2024年4月ご利用分より、My Redmine スタンダードプラン(民間企業・個人向け及び官公庁向け)とAdminサポートデスクプランの料金を改定いたします。
My Subversion ストレージ容量増量のお知らせ(一部プランを除く)
My Subversionではミディアムプラン以上の各プランのストレージ容量を増量します。
Redmineの最新情報をメールでお知らせする「Redmine News」配信中
新バージョンやセキュリティ修正のリリース情報、そのほか最新情報を迅速にお届け