Sphinx とは
Python製のドキュメント生成ツール。 特徴としては以下の通り。
- reStructuredTextで記述する（プラグインの導入によりMarkdownも可）
- ドキュメントを複数ファイルに分けて管理することができる
- 実体はプレーンテキストなのでGit等でバージョン管理可能
- ソースコードとともにバージョン管理が可能
- 図表や数式の記述も可能
最近ドキュメントの作成を依頼されるとまずsphinxが思い浮かぶ。
それくらい気に入っているツール。
インストール
それでは早速インストール
pip install sphinx
これだけ。
プロジェクトの作成
sphinx-quickstart
このコマンドを実行すると、以下の項目について対話的に聞かれます。 目的と内容にあった選択をしましょう。
- ドキュメントのルートパス
- ソースと、ビルド結果のフォルダを完全に分けるかどうか。
- Sphinxの作るシステムディレクトリの名前の先頭に付く接頭辞。
- プロジェクト名と著者名
- プロジェクトのバージョン
- ソースファイルのデフォルトの拡張子
- ドキュメントのトップページのファイル名
- 各種拡張機能をインストールするかどうか。
基本デフォルトで問題ないと思います。 これを実行すると、以下のような構成のプロジェクトディレクトリが生成されます。
project_dir ├── Makefile ├── _build ├── _static ├── _templates ├── conf.py ├── index.rst └── make.bat
ドキュメントの生成
先ほどのsphinx-quickstartで生成されたMakefileにはドキュメントを生成するためのコマンドが書かれています。
html形式で出力したい場合、以下のようにコマンドを打ちます。
make html
すると、_buildディレクトリ以下のhtmlディレクトリ内にhtml群が生成されます。
project_dir ├── Makefile ├── _build │ ├── doctrees │ │ ├── environment.pickle │ │ └── index.doctree │ └── html │ ├── _sources │ ├── _static │ ├── genindex.html │ ├── index.html │ ├── objects.inv │ ├── search.html │ └── searchindex.js ├── _static ├── _templates ├── conf.py ├── index.rst └── make.bat
試しにindex.htmlをブラウザで開いてみると、以下のような表示となります。
デフォルトでは、
- 目次（
index.html） - 索引（
genindex.html） - 検索ページ（
search.html） - モジュール索引（
modindex）
が用意されており、下3つは目次（index.html）から飛べるようになっています。
. test_project documentation master file, created by sphinx-quickstart on Tue Oct 9 00:23:36 2018. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Welcome to test_project's documentation! ======================================== .. toctree:: :maxdepth: 2 :caption: Contents: Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
Markdownの対応
一般的にはreStructuredText記法よりもMarkdown記法のほうが使われているかと思います。
Markdownへの対応は数分で終わるのでやってしまいましょう。
まず、Markdown記法の読み込みに使用するパッケージをインストールします。
pip install recommonmark
次に、Markdownを読み込めるようにconfファイルで指定してやります。 以下のように変更します。
conf.py
# The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = '.rst'
↓
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md']
# source_suffix = '.rst'
from recommonmark.parser import CommonMarkParser
source_parsers = {
'.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']
ページの追加
ではいよいよオリジナルのページを追加していきましょう。
といってもこれまた簡単で、index.rstに認識させてあげれば
project_dir中どこにおいてもオーケーです。
例えば、以下のような階層構造を持たせた（test > project1.md, project2.md）
Markdown形式のファイルを用意して、
project_dir
└── test
├── project1.md
└── project2.md
それぞれ以下のようにMarkdown記法で記述します。
project1.md
# test1 これはテストです。 これはtestです。
project2.md
# テスト２ これもテストです ## テスト２小見出し1 - あ - い - う ## テスト２小見出し2
そしてmake html
make html
これを実行すると、以下のようにhtmlが階層構造を保ったまま出力されます。
project_dir ├── _build │ └── html │ └── test │ ├── project1.html │ └── project2.html
出力結果
ちゃんとMarkdownも反映されてます。
github.ioで公開
以下のサイトがとっても丁寧
https://sky-joker.github.io/github_sphinx_example/#docs
試しに公開してみたがなぜかCSSが反映されない。。
https://nkimoto.github.io/sphinx_test/
原因わかる方いたら教えて下さいまし。
