ATENXAという名前で、VRMNXpy用のパッケージを計画中です。
汎用ライブラリとしてもお使いいただける機能があるので、リファレンスマニュアルを準備したいのですが、その方法をいつも忘れては調べ直している（そして、そこそこ時間がかかる）ので、備忘録として書き残しておきます。おきましたが、直後に結局方策を改めたので、以下、全面的に書き換えました。(9/22)
経過のあらまし
- 当初、Sphinx-apidocでのドキュメント作成を計画した。
- apidocは複雑なimport関係をもつパッケージのドキュメント化に向かないことが分かった。
- Sphinx-autosummaryをプランBとして検討したが、構文解析中のImportError (atenxaがimportできない) により、断念した。（ディレクトリ構成は合っているはずなのだが…）
- サードパーティのSphinxむけドキュメント生成ツールとして、Sphinx-automodapiを見つけた。ユーザが使用するときのパッケージの階層構造の見た目に適応してドキュメントを作ることができるとのことで、これを採用した。
必要なもの
restructured-text (reST) や Markdown をビルドしてhtmlにしてくれる。公式ドキュメントは日本語訳が中途半端で、かつ、オリジナルの英語版も難解であり、そして、巷間のブログの情報も（少なくとも日本語では）上質なものが少ないが、Python関係のドキュメントといえばデファクト・スタンダードとなっている。Pythonパッケージとして動作するので
pip install sphinx
する。
sphinx-automodapi.readthedocs.io
これも同様に、
pip install sphinx-automodapi
する。
書き出されたHTMLドキュメントの見た目のプリセットがいろいろ配布されている。有名どこだと、Read the Docsとか。
今回は、I.MAGIC御用達のMaterial for MkDocsをオマージュしたMaterial for Sphinxを使う。
pip install git+https://github.com/bashtage/sphinx-material.git
VRMNX用の拡張モジュールなので、どうしてもvrmapiモジュールに依存する。しかしこれが、通常使われるPythonシステムのsite-packagesにはないので、Sphinxのパーサーが一度ATENXAのコードを実行するときに ImportError: No module 'vrmapi' was found. が出てしまう。このエラーを回避するため、ダミーのvrmapi.pyを作っておく。
このエラーは、autodocに対しては、autodoc_mock_importsオプションによってどうやら回避できるらしい。automodapiに対する回避策として適当かは未検証である。しかし、Visual Studio Code（のPython拡張）の字句解析上のエラーメッセージを封じるためにもある程度有用なので、作っておくとよい。
def LAYOUT():
return None
def SYSTEM():
return None
def LOG(obj):
return
def CLEARLOG():
return
def ImGui():
return None
フォルダ構成
ATENXA-0.1.0alpha
├── docs
├── atenxa
│ ├── __init__.py
│ └── （他いろいろ）
├── vrmapi.py (ダミーのやつ)
└── （テスト用の.vrmnxとかいろいろ）
Sphinx のセットアップ（最初だけ）
./docs 以下にSphinx関係のもろもろをセットアップする。コマンドラインで
cd docs
sphinx-quickstart
を実行すると、対話形式でいろいろ聞かれる。
Welcome to the Sphinx 1.7.1 quickstart utility.
Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).
Selected root path: .
You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
... 途中省略
For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [ja]: (ENTER)
... 以下省略
- sourceとbuildのフォルダを分けるかと聞かれるが、分けておいたほうが整理できてよい。
- 言語を聞かれたら、
jaで日本語になる。
初期設定
sphinx-quickstartをすると ./docs に色々フォルダやファイルが生成される。
そのなかで、 ./docs/souce/conf.py と./docs/source/index.rst を編集する。
conf.py の設定
冒頭のコメントアウトされている3行を戻す。3行目はちょこっと編集して、atenxaパッケージとvrmapi.pyが見えるトップディレクトリを参照している。(conf.pyからの相対参照である。)
import os
import sys
sys.path.insert(0, os.path.abspath('../../'))
必要なSphinx拡張を有効化する。
extensions = [
'sphinx_automodapi.automodapi',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
'sphinx.ext.todo',
'recommonmark',
]
Sphinx拡張のオプションを設定する。
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
napoleon_use_rtype = False
todo_include_todos = True
テーマにsphinx-materialを指定し、細かい設定をいくつか。
html_theme = 'sphinx_material'
html_theme_options = {
'nav_title': 'ATENXA',
'color_primary': 'red',
'color_accent': 'yellow',
'globaltoc_depth': 3,
'globaltoc_collapse': False,
'globaltoc_includehidden': False,
}
index.rst の設定
indexでなくてもよいのだが、関数とその概要の一覧表を入れたい箇所に
.. automodapi:: atenxa
:no-inheritance-diagram:
こんなのを書いておく。（TOCtreeと同じ要領である。）
ドキュメントのビルド
./docsで
make clean
make html
1行目で./docs/buildを一度きれいに空にして、改めてhtmlをビルドする。
./buildにHTMLなど必要なものが書き出されるので、まとめてFTPでアップすればよい。
かなり良くできているSphinx-automodapiであるが、唯一心配なのは、あまりに知名度が低いことである。
参考
sphinx-rtd-tutorial.readthedocs.io
bashtage.github.io
www.sphinx-doc.org
www.sphinx-doc.org
