はじめに
sphinxとはpython製のオートドキュメンテーションツールである。
知的で美しいドキュメントを簡単に作れるらしい。(公式談)
今回初めてsphinxを使って文書を作成してみたので、インストールからビルドまでの流れを簡単にまとめておく。
環境
| OS | Python Ver |
|---|---|
| Windows10 | 3.10.5 |
sphinxパッケージのインストール
仮想環境を立ち上げて、環境内にインストールした。
(.venv) pip install sphinx
これで、最低限としてsphinxパッケージのインストールはOK
Read the Docsのテーマが使いたいなら追加でsphinx-rtd-themeを、バージョンごとのドキュメントを作りたい場合はsphinx-multiversionをそれぞれ適宜インストールする。
(.venv) pip install sphinx-rtd-theme sphinx-multiversion
sphinxプロジェクト作成
現在、ディレクトリ構成は以下のようになっている。
for_sphinx_test(root)/
┣━.venv/
┣━ requirements.txt
┗━ pkg/
┣━ __pycache__/
┣━ test.py
┣━ __init__.py
┗━ __main__.py
root下にdocsという名前でsphinx用プロジェクトを作成している人が多い様なので、自分もそれに倣って下記コマンドを打ちdocs内にsphinxプロジェクトを作成した。
(root) sphinx-quickstart docs
docs内にSphinx関係のファイルを作れば削除する際などに比較的楽である
sphinx-quickstartしたときに、色々質問されると思う。
Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y
soureceとbuildがごちゃごちゃするのが嫌なので自分はYを選択して、分けるようにしている。
他の質問としてプロジェクト名やauthorなど聞かれると思うがミスしたとしても、後でconf.pyで設定し直せるので気楽に答えていけばよい。
sphinxプロジェクトを立ち上げた後のディレクトリ構成は以下のようになる。
for_sphinx_test(root)/
┣━ .venv/
┣━ requirements.txt
┣━ pkg/
┃ ┣━ __pycache__/
┃ ┣━ test.py
┃ ┣━ __init__.py
┃ ┗━ __main__.py
┗━ docs/
┣━ build/
┣━ source/
┃ ┣━ _static/
┃ ┣━ _templates/
┃ ┣━ conf.py
┃ ┗━ index.rst
┣━ make.bat
┗━ makefile
quick-start後に生成されるファイルやディレクトリの用途としては以下の通り。
| ディレクトリ名/ファイル名 | 用途 |
|---|---|
| build | ビルド後に生成されるhtml等のドキュメントソース置き場 |
| _static | cssやJavaScript置き場 |
| _templates | テンプレートを上書きするファイルなどを置く |
| conf.py | 設定ファイル |
| index.rst | ドキュメントの起点になるファイル |
| make.bat | (Windows環境)ビルドを行うスクリプトが書かれたバッチファイル |
| Makefile | (Linux環境)ビルドを行うスクリプトが書かれたファイル |
ちなみに、sphinx-quickstartしたときの質問で、buildとsourceを分けなかった場合、sourceディレクトリは生成されず、中のディレクトリとファイルがbuildと同じ階層に置かれることになる。
conf.pyの設定
初めてビルドする際には、docs配下のconf.pyを少しいじらなければいけない。
いじる内容は主に3つ(うち1個は任意)
(1) パッケージディレクトリへのパス設定
ドキュメント化したいパッケージのパスを設定する必要がある。
今回はpkgのトップ階層がそれにあたる。パスはconf.pyとの相対で取るので下のようにコードを加えればよい
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
(2) extensionsの設定
初期状態ではextensionsは空リストになっていると思うがオートドキュメントのために、下の拡張を加える必要がある。
sphinxライブラリに標準で入っているので追加インストールは不要
extensions = [
'sphinx.ext.autodoc', # ソースコード読み込み用
'sphinx.ext.viewcode', # ハイライト済みのソースコードへのリンクを追加
'sphinx.ext.todo', # ToDoアイテムのサポート
'sphinx.ext.napoleon' #googleスタイルやNumpyスタイルでdocstringを記述した際に必要
]
(3) htmlテーマの変更(任意)
初期ではalabasterが設定されているはず。
自分はsphinx_rtd_themeの方がイケていると思ったのでこちらに変更した。
html_theme = 'sphinx_rtd_theme'
他にも、quick-startで設定を間違えたり、Ver情報を更新したい時などはconf.pyを変更すれば反映される。
rstファイルの作成
パッケージのパスを指定して、htmlファイルのソースとなるrstファイルを作成していく。
sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>
公式サイトでは、このような指定がある。
OUTPUT_PATHにはsourceのディレクトリを指せばよいので、rootにいた場合は次のようになる
(root) sphinx-apidoc -f -o docs/source pkg
これでモジュール毎のrstとmodules.rstというファイルが生成されたと思う。
(-f:上書き, -o:ディレクトリがなかったら作成する)
index.rstへの登録
index.rstはhtmlのトップページとして使用される。
ここにapidocで出力されたmodulesを参照させることで、htmlドキュメントが追加される仕組みのようだ。
===========================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules #これを追加
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
htmlファイルのビルド
最後にrstをhtmlへビルドする。
docsのディレクトリへ移動し、makeコマンドをたたく。
make html
または、
sphinx-build -b html ./source ./build
これで、buildディレクトリにhtmlファイルが自動生成される。
ちなみに、html以外もmake helpと打つことで、作成可能なファイル形式の一覧が表示される。
build内のindex.htmlをブラウザで表示させると生成されたものが表示される。
開くとこんな感じで、階層構造で表示される。
もちろんコードの中身も見ることができる。
自動でこれが生成されるのは非常に便利
さいごに
参考にさせていただいたサイト様には感謝いたします。
今回はsphinxを仮想環境下にインストールしたが、パッケージ毎にこれをやってしまうと、それぞれのrequirements.txtが冗長になってしまうなぁ。。と思った。
解決策としては、
(1) base環境下にsphinxを入れてしまう。(あまりやりたくない)
(2) 各パッケージをドキュメント化させるパッケージを作って集約させる。
といった感じか...(ジャストアイデアだが。)
ここら辺は今後の課題として考えどころである。
参考サイト
Sphinx documentation
Sphinx-apidoc
reSTを書かずにautodocだけでSphinxする
Sphinxを使って自作パッケージのドキュメントを簡単に更新しよう！！