Sphinx user group JPの方々がハンズオンしてくださったので、まとめ直した上でSphinxについて紹介します。
なお、この記事の内容に関する質問はこの記事のコメントにお願いします。
TL;DR
- テキストベースのドキュメントツール
- 出力は様々なドキュメントフォーマット
- ドキュメントツールなので、Webサーバとは別 (素のドキュメントのみ)
- 学習コスト低そう
- Python使いなら更に低そう
Sphinxをざっと眺める
文書を整形してくれるツール
一通りの機能がある
- 見出し
- 強調
- 斜体
- 箇条書き
メンテしやすい
- 目次の自動生成ができる
- 文書ごとに変えたい箇所を設定ファイルとして外に出せる
- 拡張機能が豊富
データの取り込みができる
- CSVファイルを読んで、整形して表示できる
- make時にコマンドも実行できる
ホスティングサービスもある
- Read the Docs https://readthedocs.org/
- オンプレミスも可能なので社内向け / 個人のクローズド利用もできる
根っこはPython
- Pythonコードを書ける。もとい困ったらPython書いちゃえば良いらしい
- Sphinxが利用しているreStructure形式はPythonの持ち物
- →大雑把に言うと、SphinxはPythonの拡張モジュールらしい
Sphinxインストール
Windows
(すいません現状では未稿です。後日試して追記予定)
(それまではお手数ですがSphinx公式サイトのインストール方法をご覧下さい)
http://www.sphinx-doc.org/ja/stable/install.html
英語版はこちら↓
http://www.sphinx-doc.org/en/stable/install.html
Linux(Cent OS 7)
sudo yum install python-pip
sudo yum install python-devel
sudo pip install sphinx
Mac
# pre check
which python
#=> /usr/bin/python
# install python 2.X
brew install python
# after check
which python
#=> /usr/local/bin/python
which pip
#=> /usr/local/bin/python
# install sphinx
pip install -U Sphinx
# version check
sphinx-build -v
#=> Sphinx v1.4.4 (with usage)
最初にやるといいもの
エディター設定
- 文字コードはUTF-8
- フォントは等幅(縦の位置を揃えたりするため)
- インデントは半角スペースで３個(ディレクティブ以外は２個)
- Tabを使うのはやめた方が良い
- reStのシンタックスハイライトができると楽(vim, emacs, atom, sublimeなど)
- vimだとriv.vim https://github.com/Rykka/riv.vim
- 補完の省力化
- 見出しの設定
- 表のアライメント
sphinx-quickstart
sphinx-quickstartのオススメ設定
- Project language [en]
- → ja (日本語にしておくのがベター)
- todo利用(todo: write “todo” entries that can be shown or hidden on build (y/N) [n]:) [n]
- → y (TODOの表示/非表示機能を使う)
Tips
テーマ(ドキュメントの外観)
- HTMLドキュメントの場合、html_themeという設定値を自分で書き換え可能
- 割と自由に選べる
- 選んだものにより、見出しの最大レベルが多少違ったりする(らしい)
箇条書き
- 記号を３種類から選べる
- 箇条書きの開始前に空行が必要(見出しの直後なら不要)
- 箇条書きの途中の空行は無視される
- 記号を変えることで箇条書きをブロック分け(カテゴリ分け)できる
見出しのレベル設定
- 基本的に１ずつ増やす
- レベル減らす際は一遍に減らせる
- h5の次にh2を書くとか
- レベル表記の見出しの後に空白行はなくても良い
表
- CSVファイルから読み込んで表にできる
- ファイルのパスは相対パス指定
- 表の列幅は全体を100とした割合(百分率)で決まる
- 幅の比を書き手が指定できる
ディレクティブ
- 拡張機能
- 自分で追加することもできる
- 便利な物はいっぱい公開されてる
toctree (目次のディレクティブ)
- 目次の最大レベル→maxdepth
- 小見出しの細かいナンバリング→numberd
- 見出しの順序を入れ替えたり、見せ方を検索条件で制御する→glob
全体を通して、慣れが必要そうな点
- インデントで縦の位置をちゃんと揃える
- 等幅フォント使えるエディタの利用を推奨
- 表も縦位置をちゃんと揃える
- AAで表を作るイメージ
- 幅変えるのはエディタの支援がないと大変そう
- ブロック単位で構造化する
- 素のPythonと同じ
- 必要な箇所に空行を入れ忘れないように気をつける
- make時に警告が出るので気づけるかも
日本のSphinxコミュニティー
※Sphinx作者はドイツの方だそうですが、日本のコミュニティーは割と活発です
#sphinxjpで検索 https://twitter.com/search?q=%23sphinxjp&src=typd
Sphinx日本ユーザグループ
- 公式ML
- 公式Slack https://sphinxjp.herokuapp.com/
Connpass
- だべり会（月１回）
- なんでもやる回（月１回）（聞いた感じだともくもく回）