社内マニュアル整備に活躍中 ドキュメント生成ツール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/04/17更新)
入門Redmine 第6版 出版記念セミナー「Redmine 8年分の新機能ふりかえり」【2024/4/18開催】
入門Redmine 第6版(2024年3月23日発売)に掲載された新機能に関する内容を執筆者・監修者が紹介します。
My Redmine 初回ご契約で「入門Redmine 第6版」プレゼントのお知らせ
Redmineのクラウドサービス「My Redmine」を初めてご契約いただいたお客様にRedmine解説書「入門Redmine 第6版」を進呈いたします。
2024年度ブランドパートナーに島根県在住のモデル ユイさんを継続起用
ユイさん(モデルスタジオミューズ所属)をファーエンドテクノロジーの2024年度ブランドパートナーとして継続して起用します。
My Redmine スタンダードプランおよびAdminサポートデスクプランの料金改定のお知らせ【2024年4月ご利用分より】
2024年4月ご利用分より、My Redmine スタンダードプラン(民間企業・個人向け及び官公庁向け)とAdminサポートデスクプランの料金を改定いたします。
Redmineの最新情報をメールでお知らせする「Redmine News」配信中
新バージョンやセキュリティ修正のリリース情報、そのほか最新情報を迅速にお届け