Sphinxを使ってみる

Sphinxを使ってみる

  • 2018.07.03
  • takahashi

お久しぶりです、デザイナーの takahashi です。
最近、Sphinxというドキュメント作成ツールを使い始めました。
今回はそれについて書いてみようと思います。

ドキュメント作成の悩み

文章を書く → 図を入れる → 文章を組み替える → 図の配置が気になる
遷移図を描く → 遷移図を変更する → レイアウトを組み直す → 細かい部分がきになる

ドキュメント・資料を作っていると、構成・内容の編集とレイアウト・デザインの編集を行ったり来たりすることがよくあります。あらかじめ書くものが決まっている場合は良いですが、書きながら構成を考える場合や後から追加する場合など、内容の変更に従ってレイアウトを組み直したりするので予想以上に時間がかかってしまったりします。

ルールを決めウェブサイトの様に内容のみ編集、見た目は後から調整可能にしたいなと思い、それ専用のサイトの仕組みを作る事を考えたりしてましたが、実際作るとそこそこ時間がかかってしまうので、何かいい方法はないかなと探していたところSphinxを見つけ、便利そう!試してみよう!」と思い立ちました。

Sphinxとは

Pythonの公式ドキュメントなどで使用されている、ドキュメンテーションツールとのことです。Sphinx自体もPythonで作られています。個人的に魅力を感じるSphinxの利点をあげると以下のような感じでしょうか。

  • プレーンテキストで編集を行うのでバージョン管理が楽
  • テーマを設定していろんな表示に切り替えられる
  • PDFにも出力できるらしい(未確認)
  • 拡張機能のblockdiagで遷移図を生成できる
  • ソースコードのハイライトも対応

それではさっそくインストールしてみます。
* 使用環境がMacのため操作の解説は基本Macでの手順になります。

http://www.sphinx-doc.org/ja/stable/install.html

この部分はログを取っていなかったため記憶が曖昧ですが、Python2系とPython3系の違いを調べてPyenvを導入して見たり、紆余曲折した末にパッケージシステムを利用してインストールしたと思います。

既にPythonの環境がある場合は以下のコードを実行してインストールできます。

プロジェクトを準備する

環境は整ったのでさっそく使ってみましょう。
ターミナル上で、ファイルを新たに作成したいディレクトリまで移動して以下のコマンドを実行します。今回はホームディレクトリ下の work フォルダに sphinx-test というフォルダを作成、その中にプロジェクトを作成しようと思うので以下のようにしました。

2行目と3行目は $ mkdir -p sphinx-test; cd $_ のように省略できますね。こっちの方が格好いい!でも次やるときには忘れそうです・・・。

さて、sphinx-quickstart を実行した途端、たくさん質問されます。

ひとつめの質問はソースとビルドのディレクトリを分けるかどうか。デフォルトではnoになっていますがファイルが増えてくると見通しが悪くなるので個人的にYesで。それ以降は www.sphinx-doc.orgの「Sphinxの最初の一歩」を参考に「autodoc 拡張に関する質問」だけは YES に、それ以外はデフォルト値が設定されているので「うんうん」と首を縦に振り続けてみます。

「うんうん」言ってると、プロジェクト名、著者名を入れてねって赤文字で怒られます。

「うんう・・・

あとで変更できそうだけど、日本語にしておいた方がいいかな。

きました、Yes にします。あとはうなずき続けて完了。

使ってみる

先ほど作ったフォルダの下にファイルができています。
さっそくビルドしてみましょう。以下のコードを入力して実行します。

build フォルダ内に html フォルダが追加されました!
html フォルダ内の index.html を開きます。

できました!

・・・このままだと閑散としていて寂しいので、テーマを入れてみましょう。
テーマは conf.py を編集することで切り替えられます。Options for HTML output と書かれたセクションの html_theme の値を変更します。また、オプションが設定できるテーマでは、html_theme_options を編集して表示をカスタマイズできるようです。

公式ドキュメントから「HTMLテーマのサポート」のページを見てみます。
http://www.sphinx-doc.org/ja/stable/theming.html

Sphinx には組み込みテーマが用意されていて、名前を入れるだけで使えます。今回はいろいろ試してみて、しっくりくるものがなかったので「Third Party Themes」の項目で紹介されている sphinx_rtd_theme をインストール&使ってみることにしました。

テーマのインストールは pip コマンドで行います。

テーマのインストールが完了したら、html_theme_optionsの値をもう一度以下のコードを実行して表示反映!

いい感じですね。

自分の場合は pip が古いためアップグレードしてくださいのメッセージが表示されたので pipのアップグレードも同時に行いました。

まとめ

長くなってしまったのでこの辺りで。
使ってみた感想としては、

  • テキストベースなのでGitで管理、変更箇所を参照できるのは楽
  • 内容とテーマを分けられるので内容に集中できるのがよい
  • 最初の設定が少々面倒
  • ドキュメントの記述方法を覚えるまで慣れが必要
  • コマンドライン操作なのでチームで編集する場合はハードルが高いかも

という感じです。

個人的にドキュメントを蓄積していくのには使えると感じたので、しばらく使ってみる予定。今回、内容の方まで踏み込めませんでしたが、そのうち実際のドキュメントや遷移図の作成、活用法などについて書けたらいいなと思います。

PAGE TOP

PAGE TOP