お久しぶりです、デザイナーの takahashi です。
最近、Sphinxというドキュメント作成ツールを使い始めました。
今回はそれについて書いてみようと思います。
文章を書く → 図を入れる → 文章を組み替える → 図の配置が気になる
遷移図を描く → 遷移図を変更する → レイアウトを組み直す → 細かい部分がきになる
ドキュメント・資料を作っていると、構成・内容の編集とレイアウト・デザインの編集を行ったり来たりすることがよくあります。あらかじめ書くものが決まっている場合は良いですが、書きながら構成を考える場合や後から追加する場合など、内容の変更に従ってレイアウトを組み直したりするので予想以上に時間がかかってしまったりします。
ルールを決めウェブサイトの様に内容のみ編集、見た目は後から調整可能にしたいなと思い、それ専用のサイトの仕組みを作る事を考えたりしてましたが、実際作るとそこそこ時間がかかってしまうので、何かいい方法はないかなと探していたところSphinxを見つけ、便利そう！試してみよう！」と思い立ちました。
Pythonの公式ドキュメントなどで使用されている、ドキュメンテーションツールとのことです。Sphinx自体もPythonで作られています。個人的に魅力を感じるSphinxの利点をあげると以下のような感じでしょうか。
それではさっそくインストールしてみます。
* 使用環境がMacのため操作の解説は基本Macでの手順になります。
http://www.sphinx-doc.org/ja/stable/install.html
この部分はログを取っていなかったため記憶が曖昧ですが、Python2系とPython3系の違いを調べてPyenvを導入して見たり、紆余曲折した末にパッケージシステムを利用してインストールしたと思います。
既にPythonの環境がある場合は以下のコードを実行してインストールできます。
$ pip install sphinx
環境は整ったのでさっそく使ってみましょう。
ターミナル上で、ファイルを新たに作成したいディレクトリまで移動して以下のコマンドを実行します。今回はホームディレクトリ下の work フォルダに sphinx-test というフォルダを作成、その中にプロジェクトを作成しようと思うので以下のようにしました。
$ cd work
$ mkdir sphinx-test
$ cd sphinx-test
$ sphinx-quickstart2行目と3行目は $ mkdir -p sphinx-test; cd $_ のように省略できますね。こっちの方が格好いい！でも次やるときには忘れそうです・・・。
さて、sphinx-quickstart を実行した途端、たくさん質問されます。
> Separate source and build directories (y/N) [n]: ひとつめの質問はソースとビルドのディレクトリを分けるかどうか。デフォルトではnoになっていますがファイルが増えてくると見通しが悪くなるので個人的にYesで。それ以降は www.sphinx-doc.orgの「Sphinxの最初の一歩」を参考に「autodoc 拡張に関する質問」だけは YES に、それ以外はデフォルト値が設定されているので「うんうん」と首を縦に振り続けてみます。
「うんうん」言ってると、プロジェクト名、著者名を入れてねって赤文字で怒られます。
> Project name: sphinx-test
> Author name: takahashi「うんう・・・
> Project language[en]: jaあとで変更できそうだけど、日本語にしておいた方がいいかな。
> autodoc: automatically insert docstrings from modules (y/n) [n]: yきました、Yes にします。あとはうなずき続けて完了。
先ほど作ったフォルダの下にファイルができています。
さっそくビルドしてみましょう。以下のコードを入力して実行します。
$ make htmlbuild フォルダ内に html フォルダが追加されました！
html フォルダ内の index.html を開きます。
できました！
・・・このままだと閑散としていて寂しいので、テーマを入れてみましょう。
テーマは conf.py を編集することで切り替えられます。Options for HTML output と書かれたセクションの html_theme の値を変更します。また、オプションが設定できるテーマでは、html_theme_options を編集して表示をカスタマイズできるようです。
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}公式ドキュメントから「HTMLテーマのサポート」のページを見てみます。
http://www.sphinx-doc.org/ja/stable/theming.html
Sphinx には組み込みテーマが用意されていて、名前を入れるだけで使えます。今回はいろいろ試してみて、しっくりくるものがなかったので「Third Party Themes」の項目で紹介されている sphinx_rtd_theme をインストール＆使ってみることにしました。
テーマのインストールは pip コマンドで行います。
$ pip install sphinx_rtd_themeテーマのインストールが完了したら、html_theme_optionsの値をもう一度以下のコードを実行して表示反映！
$ make html
いい感じですね。
自分の場合は pip が古いためアップグレードしてくださいのメッセージが表示されたので pipのアップグレードも同時に行いました。
you are using pip version 10.0.0. however version 10.0.1 is avilable
You should consider upgrading via the 'python -m pip install --upgrade pip' command.
$ sudo pip install --upgrade pip長くなってしまったのでこの辺りで。
使ってみた感想としては、
という感じです。
個人的にドキュメントを蓄積していくのには使えると感じたので、しばらく使ってみる予定。今回、内容の方まで踏み込めませんでしたが、そのうち実際のドキュメントや遷移図の作成、活用法などについて書けたらいいなと思います。