Blog

Sphinxでドキュメント生成してカスタマイズするまで

2019.04.09Cat:開発

はじめに

新しく入るエンジニアに向けてのドキュメント作りの一環としての備忘録です

本投稿で扱う内容

  • Sphinxインストールの復習
  • テーマの変更
  • 目次インデックスの基本
  • 自動採番、テーブルなど

インストール

python3.6を使用します。

iusリポジトリをインストール後
python3.6(pip3.6含む)を導入してsphinxのインストールまで(CentOS6.9)

シンボリックリンクを貼る(python3.6 という実行名を python3と略すため)

Sphinxをインストール

ここで必要な設定項目を入れる。
nginx, apacheなどのDocumentRootは/var/www/html/sample_sphinx/build/htmlに設定するだけ。

テーマの変更

初期状態はこのような感じ。

テーマはhttps://sphinx-themes.org/などからプレビューから選べます。
各テーマの”pypi”リンクからたどり着くページにある「pip3 install テーマ名」のコマンドを実行し
source/conf.py にテーマ名の指定をするだけです。

以下、astropyの例。

これだけ。

目次インデックス

SphinxはデフォルトではreStructuredTextという文法に従って書きます。
Markdownへの対応も設定次第で可能ですが、最終的にreStructuredTextを憶えた方が色々と出来そうだったので初期値のままで。

目次インデックスは以下のよう。

toctree構文でページ内に目次を簡単に造ることが可能。
また採番は “:numbered:” オプションを正しく記述すればOK。

※ 注意
toctreeオプションは同じインデントに揃えないと反映されません!

このようにページを用意した場合、トップは以下のようになります
また、numberedオプションを入れると、見出しの階層レベルを仕様に従って記述することで

このように自動採番されます。途中で項目が増えても平気。

自動ビルド

sphinxはrstファイル群からhtml等へコンバートするためのビルドが必要です。
いちいち編集するたびに make html を実行するのが面倒という方は以降参照。

Author Profile

OBA
ランニングと音楽とヲタトーク好きプログラマーです。 数学と英語を勉強中です。 DeepLearning始めました!
» 投稿一覧
     
  • Launch Cart越境ECカート

Archive

ページTOPへ