2019/04/10
Sphinxでドキュメント生成してカスタマイズするまで
はじめに
新しく入るエンジニアに向けてのドキュメント作りの一環としての備忘録です
本投稿で扱う内容
- Sphinxインストールの復習
- テーマの変更
- 目次インデックスの基本
- 自動採番、テーブルなど
インストール
python3.6を使用します。
iusリポジトリをインストール後
python3.6(pip3.6含む)を導入してsphinxのインストールまで(CentOS6.9)
|
1 2 | yum install -y https://centos6.iuscommunity.org/ius-release.rpm yum install -y python36* |
シンボリックリンクを貼る(python3.6 という実行名を python3と略すため)
|
1 2 | ln -s /usr/bin/python3.6 /usr/bin/python3 ln -s /usr/bin/pip3.6 /usr/bin/pip3 |
Sphinxをインストール
|
1 2 3 4 | cd /var/www/html/ mkdir -p sample_sphinx cd sample_sphinx sphinx-quickstart |
ここで必要な設定項目を入れる。
nginx, apacheなどのDocumentRootは/var/www/html/sample_sphinx/build/htmlに設定するだけ。
テーマの変更
初期状態はこのような感じ。
テーマはhttps://sphinx-themes.org/などからプレビューから選べます。
各テーマの”pypi”リンクからたどり着くページにある「pip3 install テーマ名」のコマンドを実行し
source/conf.py にテーマ名の指定をするだけです。
以下、astropyの例。
|
1 | pip3 install astropy-sphinx-theme |
|
1 | html_theme = 'bootstrap-astropy' |
これだけ。
目次インデックス
SphinxはデフォルトではreStructuredTextという文法に従って書きます。
Markdownへの対応も設定次第で可能ですが、最終的にreStructuredTextを憶えた方が色々と出来そうだったので初期値のままで。
Markdownへの対応も設定次第で可能ですが、最終的にreStructuredTextを憶えた方が色々と出来そうだったので初期値のままで。
目次インデックスは以下のよう。
toctree構文でページ内に目次を簡単に造ることが可能。
また採番は “:numbered:” オプションを正しく記述すればOK。
※ 注意
toctreeオプションは同じインデントに揃えないと反映されません！
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | .. sphinx documentation master file, created by sphinx-quickstart on Tue Apr 9 06:19:55 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to sphinx's documentation! ================================== .. toctree:: :maxdepth: 2 :caption: Contents: first second Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` |
|
1 2 3 4 5 6 | First section ============================== title --------------- body |
|
1 2 3 4 5 6 | Second section ============================== title --------------- body |
このようにページを用意した場合、トップは以下のようになります
また、numberedオプションを入れると、見出しの階層レベルを仕様に従って記述することで
このように自動採番されます。途中で項目が増えても平気。
自動ビルド
sphinxはrstファイル群からhtml等へコンバートするためのビルドが必要です。
いちいち編集するたびに make html を実行するのが面倒という方は以降参照。
いちいち編集するたびに make html を実行するのが面倒という方は以降参照。
|
1 | pip3 install sphinx-autobuild |
|
1 2 | livehtml: sphinx-autobuild -b html $(SOURCEDIR) $(BUILDDIR)/html |
Author Profile
スターフィールド編集部
SHARE