Sphinxは非常に素晴らしいドキュメント生成ツールです。
この素晴らしいツールを社内で流行らせようと頑張ったのですが、誰も使ってくれません。

みんながどんなタイミングで、Sphinxを諦めてしまうのか振り返ってみました。

reStructuredTextがわからないし、覚えたくもない
デフォルトのテーマが見にくいからやめる
sphinx-quickstartの設問が多すぎて途中でやめる
ドキュメント作成のたびにconf.pyを編集するのが面倒なので使わなくなる
ドキュメント確認のたびにmake htmlが面倒なので使わなくなる
最近はJupyterでドキュメント書くので・・・

こんなところでしょうか。
たぶん、Sphinxがいまいち流行らないのも、ここら辺が理由が大きいんじゃないかと思います。

Markdownを使う

残念ながらマークアップ言語の主流はreStructuredTextではなくMarkdownです。Markdownならみんなに使ってもらえるんじゃないでしょうか。

SphinxはrecommonmarkでMarkdownを使えるようになります。
recommonmarkの設定方法は、たくさんの方が記事を書いています、以下の記事などを参考にしてください。

recommonmarkはpipでインストール可能です。

pip install commonmark recommonmark

conf.pyを以下のように編集します。

conf.py

source_suffix = ['.rst', '.md']

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

さらにrecommonmarkを拡張するAutoStructifyコンポーネントについて説明します。

AutoStructifyコンポーネント

AutoStructifyコンポーネントをセットアップすると、マークダウンからreStructuredTextの様々な拡張が使えるようになります。
AutoStructifyコンポーネントを有効にするにはconf.pyを編集します。

conf.py

from recommonmark.transform import AutoStructify

github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

マークダウン上で、以下のことができるようになります。

toctree生成
他文書のリンク
数式 / インライン数式¹
reStructuredTextの埋め込み

toctree生成

マークダウン記法

* [Title1](doc1.md)
* [Title2](doc2.md)

他文書のリンク

マークダウン記法

[API Reference](api_ref.md)

数式 / インライン数式

マークダウン記法

```math
E = m c^2
``` ``

インライン数式も使えます。

マークダウン記法

This formula `$ y=\sum_{i=1}^n g(x_i) $`

参考
http://recommonmark.readthedocs.io/en/latest/auto_structify.html

Commonmarkの「表組み」が使えない問題

recommonmarkでマークダウンが書けるのは良いのですが、表組み(テーブル)が使えません。
これはCommonMarkが表組みはサポートしていないためで、近い未来に表組みがサポートされる事はなさそうです。

recommonmarkのGitHubでもイシューが上がっていましたが「eval_rst使えばいいんじゃね？」という事になっています。

表組みに関して言えばreStructuredTextの方が表現力が高いですし、eval_rstであればマークダウンの記述を崩さないので、ひとまずはこれで良いかなと思っています。

eval_rstで表組みは以下のようにします。

```eval_rst
=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======
``` ``

見やすいテーマを設定する

とりあえずMarkdown、およびその拡張が使えるようになったので、結構便利になってきました。
あとは見やすいテーマの設定です。

いくつかのテーマを試ましたが、やはりRead The Docsテーマが一番見やすいと思います。

インストールpipで簡単に行えます。

pip install sphinx_rtd_theme

後はconf.pyを編集します。

conf.py

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

かなり見やすくなりましたね！！

ドキュメント生成を簡単にする

テーマも見やすくなって、かなり便利になってきましたね。

さて、いままでMarkdownの設定して、テーマを設定して、結構な量のconf.pyを編集してきました。
この作業はドキュメントを作る度に毎回行う必要があります、不便すぎるわ、なんだそれ。

さすがに毎回conf.pyを編集は辛すぎます、テンプレート機能を使いましょう。

** 注意 **
現状、conf.pyのテンプレートを使用するにはSphinxのバージョン(1.5.2)のソースファイルを編集します。
行う場合は自己責任でおねがいします。

テンプレート機能を使う

sphinx-quickstartには--templatedirというオプションが用意されています。
sphinx-quickstartはjinja2を使って、conf.pyやMakefileなどのもろもろのファイルをテンプレートから生成しています。

ここで散々いじったconf.pyを雛形としたテンプレートファイルを用意すれば良いのです！

テンプレートファイルの雛形は以下の場所にあるはずです、各環境にあわせて適宜読み替えてください。

Pythonのパス/site-packages/Sphinx-x.x.x-pyx.x.egg/sphinx/templates/quickstart

ファイルが見つからない場合はconf.py_tというファイルを検索して見つけてください。
recommonmarkとrtd_themeの設定をしたconf.py_tをgistに乗せておきます。

conf.py_tをどこか適当なディレクトリに置いてください。
なお、テンプレートディレクトリにファイルがいくつかありますが、sphinx-quickstartのソースを読む限り、存在しないテンプレートファイルはシステムのテンプレートファイルを見るようなので、すべてのファイルをコピーする必要はありません。

テンプレートファイル名	説明
conf.py_t	conf.pyのテンプレート
Makefile.new_t	シンプル版Makefileのテンプレート
Makefinle_t	Makefileのテンプレート
make.bat.new_t	シンプル版make.batのテンプレート
make.bat_t	make.batのテンプレート
master_doc.rst_t	最初に生成される.rstのテンプレート

しかし、conf.pyが書き換わらない！

テンプレートファイルを格納したディレクトリを指定してsphinx-quickstartを実行します。

sphinx-quickstart --templatedir=my_sphinx_template

しかし、何回コマンドを実行してもconf.pyが書き換わりません。
Makefileなど他のファイルは書き換わるのにconf.pyはどうしても書き換わらないのでソースを読みます。

sphinx/quickstart.pyの442行目でコードが以下のようになっています。

quickstart.py

    with open(os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')) as f:
       conf_text = convert_python_source(f.read())

conf.py_tだけ直接パッケージ配下のファイルを直指定しています。

quickstart.py

    # with open(os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')) as f:
    conf_path = os.path.join(templatedir, 'conf.py_t') if templatedir else None
    if not conf_path or not path.isfile(conf_path):
        conf_path = os.path.join(package_dir, 'templates', 'quickstart', 'conf.py_t')
    with open(conf_path) as f:
        conf_text = convert_python_source(f.read())

※ template_dirがNoneの場合にエラーが出ていました、修正いたします(2017/02/05)

conf.pyでテンプレートが使えないのは不便すぎるので、ソースを書き換えてしまいます。

Sphinxのソース書き換えについて(2017-02-08追記)

現状でconf.pyにテンプレート機能が効かないのはバグとなります。

上記の変更をプルリクエストしてマージされましたので、３月中頃にリリース予定の1.5.3では修正される予定です。
初めてGithubでプルリクエストを出したのですが色々失敗をしました、付き合ってくださったSphinxコントリビュータの方に感謝いたします。

sphinx-quickstartを便利にする

テンプレートの件は少しモヤモヤしますが、毎回のconf.py編集から解放されて、だんだん便利になってきました。
sphinx-quickstartは、バージョンを重ねるごとに項目が増えてきて、もはやクイックではない問題です。

sphinx-quickstartは色々なオプションが用意されているので、すべてのオプションを適用したバッチファイルを作れば良いのですが、オプション数が多いので非常に面倒です。

そこでクイックスタートをクイックにするPythonスクリプトを書こうと思います。

my-sphinx-quickstart.py

# ! codig:utf-8
import sys
from sphinx.quickstart import ask_user, generate, DEFAULT_VALUE

d = DEFAULT_VALUE.copy()

d["path"] = sys.argv[1]
d["project"] = sys.argv[2]
d["author"] = sys.argv[3]

# 決め打ちの設定
d["version"] = "1.0"
d["language"] = "ja"

# シンプルなMakefile
d["make_mode"] = True

# エクステンションの設定
d["ext_mathjax"] = True

template_dir = "テンプレートパスまたはNone"

# 不足パラメータがあった場合の質問（無くてもよい、お好みで）
ask_user(d)

# ドキュメント生成
generate(d, templatedir=template_dir)

内容は各自で書き換えてください。
上の例ではプロジェクトパス、プロジェクト名、作者名を引数にして実行すると、後はすべてデフォルト設定でドキュメントを作成してくれます。

基本的にsphinx.quickstart.generateメソッドにパラメータ辞書とテンプレートディレクトリを渡す事でドキュメントを作成しています。
Jsonで設定を外部ファイルに移したり、GUIで設定するスクリプトとかを書くと便利かもしれません。

このスクリプトとテンプレートディレクトリを社内で共有すれば、カスタムされたドキュメント生成が一瞬で作れるようになります。
これは便利に違いない。

2017-03-06追記

Sphinxのドキュメント作成を便利にする「sphinx-quickstart-plus」を作りましたを書きました、この記事のconf.pyの設定が自動生成されるツールです。

sphinx-autobuildを使って自動ビルドをする

これでドキュメント作成時に、わずらわしいsphinx-quickstartとconf.pyの編集から解放されました。
この時点で、かなり便利になったかと思います。

ドキュメントを更新＆確認するごとに、いちいちmake htmlを打たなくてはいけないのですが、sphinx-autobuildを使うと自動でビルドされるようになります。

pipでインストール可能です。

pip install sphinx-autobuild

インストール後に以下のコマンドでファイル監視が始まり、更新と同時にビルドされます。

sphinx-autobuild  <ソースディレクトリ> <ビルド成果物出力ディレクトリ>

このコマンドは長くなるので毎回入力するのは面倒です、なので生成されたMakefileに次のコードを付け足すと便利です。

Makefileの場合

livehtml:
	sphinx-autobuild -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

NewMakefileの場合

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

※Makefileの仕様としてインデントはTABにしないとエラーになります、注意してください

以下のコマンドで自動ビルド監視が始まります。

make livehtml

localhost:8000でドキュメントにアクセスします。
ちなみに先に話したテンプレート機能でMakefile_tとMakefile.new_tに、それぞれのコードを追加しておくと便利です。

gistにMakefile_tとMakefile.new_tのテンプレートを乗せておきます。

Jupyterのノートブックを取り込む(2017-02-06追加)

最近はJupyterを使ってドキュメントを書く人も増えてきたと思います。
Sphinxの拡張にnbsphinxというものがあり、この拡張でJupyterノートブックを取り込むことができます。

インストールはpipで簡単に行えます。

pip install nbsphinx

例によってconf.pyを編集します。

conf.py

extensions = [
    'nbsphinx',
    'sphinx.ext.mathjax',
]
exclude_patterns = ['_build', '**.ipynb_checkpoints']

nbsphinx拡張と無視パターンに**.ipynb_checkpointsが入っている事を確認してください。

次にtoctreeにノートブックを追加します、拡張子.ipynbを除去したファイル名を書いてください。
なお、ノートブックの1行目に見出し（# タイトル)を入れないと、認識されないので注意してください。

下の例ではjupyter.ipynbというファイルを文書として追加している例です。

Welcome to test's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   jupyter

Jupyterノートブックが追加されました！
nbsphinxもconf.py_tのテンプレートに追加しておくと便利でしょう。

Font Awesomeを使う(2017-02-11追加)

Font Awesomeは様々なフォントアイコンでドキュメントの表現力を上げてくれます。
QiitaもFont Awesomeに対応しています。

SphinxでFont Awesomeを使うにはsphinx_fontawesomeを使います、インストールは例によりpipで簡単に行なえます。

pip install sphinx_fontawesome

conf.pyを編集します。

import sphinx_fontawesome
extensions = ['sphinx_fontawesome']

マークダウンから使いたい場合は普通にHTMLを打ちます。

<i class="fa fa-exclamation-triangle" aria-hidden="true"></i>

このようにSphinxのマークダウンからFont Awesomeが使えます。

reStructuredTextからの使い方はsphinx_fontawesomeのReadmeで参照してください。

AtomでreStructuredTextをプレビューする

reStructuredTextで頑張りたい人は、AtomにreStructuredTextをプレビューするプラグインがあります。

rst-preview: https://atom.io/packages/rst-preview

ctrl-shift-rでプレビューを表示できます、pandocを使うので先にインストールしておいてください。

あとがき

Sphinxは様々なところで不便なところがありましたが、環境さえ整備すれば、かなり便利になります。

Markdownでドキュメントが書ける
いざとなったらreStructuredTextも混ぜて書くことができる
Jupyterノートブックも取り込める
自動ビルドもしてくれる
拡張も豊富
Pythonとの高い親和性
ドキュメント生成もスクリプトで一発

最強のドキュメント環境に近づいたんじゃないかと思います。

~~最後に、テンプレート機能でconf.pyを書き換えるソース改造は自己責任で、またはSphinxのバージョン1.5.3を待ってください。~~
テンプレートに関しては最新版のSphinx 1.5.3で修正されています。

2017-03-06追記

Sphinxのドキュメント作成を便利にする「sphinx-quickstart-plus」を作りましたを書きました、この記事のconf.pyの設定が自動生成されるツールです。

数式を使うにはsphinx.ext.mathjaxなどの拡張を有効にする必要があります ↩