自分用技術メモの作成が捗ったSphinxのあれこれについて

# はじめに

この記事は[Hamee Advent Calendar 2016](http://qiita.com/advent-calendar/2016/hamee)の17日目の記事です。

少し前から個人的に[Sphinx](http://docs.sphinx-users.jp/)（Python製のドキュメンテーションツール）に触れていて、**試しに自分用の技術メモの作成にSphinxを使ってみたら思った以上に捗った**ので、その際に使った機能や拡張機能について書いていきます。

## 注意

この記事ではSphinxの詳細についてはほとんど紹介しません。
あくまで**こんな機能・拡張機能を使ったら便利だったよ！**といった ~~ポエム~~ 内容の記事となっていますので、あらかじめご了承ください。


# TOCツリーのおかげで見通しが良く管理しやすい

メモを1つのファイルに書いていくと、あれもこれもと書いているうちに次第に内容が膨大になっていき、**後で振り返りをしようと思ったらメモが読みづらい**とか**内容を追加しようと思ったらどこに何が書いてあるかわかりづらい**…なんてこともあるかと思います。

```:note.md（1つのファイルでメモを管理する例）
# Note

## gitについて

### add

...

### commit

...

## PHPについて

### Docコメント

...
```

Sphinxには[TOCツリー](http://docs.sphinx-users.jp/markup/toctree.html)という便利な機能（ディレクティブ）があり、TOCツリーのおかげでファイル自体を分割したり内容ごとにディレクトリを分けて管理しても文章の構造を維持することができます。

```sh:ディレクトリ構成
source
├── conf.py
├── git
│   └── index.rst
├── index.rst
├── mysql
│   └── index.rst
└── php
    └── index.rst
```

```rst:index.rst
Note
====

.. toctree::
    :maxdepth: 2

    git/index
    php/index
```

```rst:git/index.rst
gitについて
===========

add
---

...

commit
------

...
```

```rst:php/index.rst
PHPについて
===========

Docコメント
-----------

...
```

`make html`を実行すると、以下のようなHTMLが出力されます。

![スクリーンショット 2016-12-17 15.26.09.png](https://qiita-image-store.s3.amazonaws.com/0/101189/ea3afa2d-3d92-e662-9154-e9908f179a47.png)

メモの内容によって**ファイルやディレクトリを分割しているので見通しが良く**なり、それでいて**1ファイルでメモを作成する場合と同様のツリー構造を維持することができる**ので、管理が楽になって個人的にはとても良いと思います！


# 使い慣れたMarkdownで手軽にメモを書くことができる

Sphinxを使おうと思ったら[reStructuredText（reST）](http://docs.sphinx-users.jp/rest.html)と呼ばれる記法を覚える必要があって学習コストが掛かりそう…それならSphinxなんて使わなくていいや…そう思っていた時期が私にもありました。

[recommonmark](https://recommonmark.readthedocs.io/en/latest/)を導入すれば、**SphinxでMarkdownを使うことができる**ようになります。
導入の手順は`pip`で`recommonmark`モジュールをインストールして、`source/conf.py`に設定を追加するだけです。

```shell:recommonmarkのインストール
pip install recommonmark
```

```diff:souce/conf.pyのdiff
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+from recommonmark.parser import CommonMarkParser
+
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
+source_suffix = ['.rst', '.md']
```

上記の設定をすればMarkdownを使うことができるようになるので、reSTは**ほとんど**書かずに済みます。
※ただし、先述のTOCツリーディレクティブのようなreST特有の機能を使用する際にはもちろんreSTを書く必要があります。

今回の例だと、`git/index.rst`を`git/index.md`に、`php/index.rst`を`php/index.md`にそれぞれ置き換えることができます。

```shell:ディレクトリ構成
source
├── conf.py
├── git
│   └── index.md
├── index.rst
└── php
    └── index.md
```

```:git/index.md
# gitについて

## add

...

## commit

...
```

```:php/index.md
# PHPについて

## Docコメント

...
```

reSTからMarkdownに置き換えても、`make html`を実行して生成されるHTMLに変更はありません。

![スクリーンショット 2016-12-17 17.10.02.png](https://qiita-image-store.s3.amazonaws.com/0/101189/50a7074b-97da-bd22-9ec9-46b01d77c5bc.png)

上記の設定さえ済ませてしまえば**ほとんどの部分はMarkdown形式で書くことができる**ので、学習コストをあまり掛けることなく見通しの良いメモを作成することができるようになります！


# 編集後の確認までの手順が自動化できる

メモを編集してからHTMLを作成し直して、改めてブラウザ上で内容を確認しようとすると

1. メモを編集して保存
2. ターミナルで`make html`を実行してHTMlをビルドし直す
3. ブラウザに移動してリロード
4. 内容を確認

といった手順が必要で、これを編集する度に繰り返すのは少し面倒だと思います。
ところが、この手順は[sphinx-autobuild](https://github.com/GaretJax/sphinx-autobuild)を導入することで自動化できます！

まずは`recommonmark`導入時と同様に、`pip`で`sphinx-autobuild`モジュールをインストールします。

```shell:sphinx-autobuildのインストール
pip install sphinx-autobuild
```

あとは`sphinx-autobuild`を実行して`http://127.0.0.1:8000`（デフォルトの設定の場合）を表示しておけば、**ソースファイルを編集して保存するだけでHTMLがビルドされて、更にブラウザがリロード**されます。

`sphinx-autobuild`の実行時には、ソースファイルのディレクトリとHTML出力先のディレクトリを指定します。

```shell:sphinx-autobuildの実行
sphinx-autobuild souce build/html
```

下記のように`index.rst`を編集（`Hello, world!`という1行を追加）して保存すると

```rst:index.rst
Note
====

Hello, world!

.. toctree::
    :maxdepth: 2

    git/index
    php/index
```

自動的に以下のような処理が走ってHTMLが再ビルドされて

![スクリーンショット 2016-12-17 18.07.40.png](https://qiita-image-store.s3.amazonaws.com/0/101189/f6dd6822-3c71-865b-d9b8-8a4f0e9c4ee0.png)

更に自動的にブラウザがリロードされ、編集した内容が反映されていることが確認できます。

![スクリーンショット 2016-12-17 18.11.16 のコピー.png](https://qiita-image-store.s3.amazonaws.com/0/101189/5bfa7f87-96a0-bb59-b0c0-cc1c1d39597b.png)

コマンドさえ実行しておけば**ファイルの編集後にHTMLを確認するまでの手順を自動化することができる**ので、メモを書くことに集中できます！

ちなみに、`Makefile`に下記の設定を追加しておけば実行するコマンドが`make livehtml`で済むので非常に楽になります。

```basemake:Makefile
livehtml:
	sphinx-autobuild -b html $(SOURCEDIR) $(BUILDDIR)/html
```

# おわりに

本格的なドキュメント作成のためにSphinxを運用しているというわけではありませんが、自分用の技術メモを作成するために試しに使ってみたらとても便利でした！
使い始めたばかりでまだまだ知識が浅いですが、徐々にreSTにも慣れていき更に便利にSphinxを使いこなせるようになりたいところです。

Sphinxはいいぞ！