AKAGI Rails

鉄道模型シミュレーターで遊んでいたはずが、気づいたらPythonなども。

Sphinx-automodapiでVRMNX用パッケージのリファレンスを作る

ATENXAという名前で、VRMNXpy用のパッケージを計画中です。

f:id:AKAGI-vrmstation:20201013234850p:plain

汎用ライブラリとしてもお使いいただける機能があるので、リファレンスマニュアルを準備したいのですが、その方法をいつも忘れては調べ直している(そして、そこそこ時間がかかる)ので、備忘録として書き残しておきます。おきましたが、直後に結局方策を改めたので、以下、全面的に書き換えました。(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テーマ

書き出されたHTMLドキュメントの見た目のプリセットがいろいろ配布されている。有名どこだと、Read the Docsとか。

今回は、I.MAGIC御用達のMaterial for MkDocsをオマージュしたMaterial for Sphinxを使う。

pip install git+https://github.com/bashtage/sphinx-material.git
  • ダミーの vrmapi.py

VRMNX用の拡張モジュールなので、どうしてもvrmapiモジュールに依存する。しかしこれが、通常使われるPythonシステムのsite-packagesにはないので、Sphinxのパーサーが一度ATENXAのコードを実行するときに ImportError: No module 'vrmapi' was found. が出てしまう。このエラーを回避するため、ダミーのvrmapi.pyを作っておく。

このエラーは、autodocに対しては、autodoc_mock_importsオプションによってどうやら回避できるらしい。automodapiに対する回避策として適当かは未検証である。しかし、Visual Studio Code(のPython拡張)の字句解析上のエラーメッセージを封じるためにもある程度有用なので、作っておくとよい。

# -*- coding: utf-8 -*-
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.ext.autodoc',
    #'sphinx.ext.autosummary',
    'sphinx_automodapi.automodapi',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'recommonmark',
]

Sphinx拡張のオプションを設定する。

source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}

#autodoc_mock_imports = ['vrmapi']
#autodoc_member_order = 'bysource'
napoleon_use_rtype = False
todo_include_todos = True

テーマにsphinx-materialを指定し、細かい設定をいくつか。

html_theme = 'sphinx_material'

# Material theme options (see theme.conf for more information)
html_theme_options = {

    # Set the name of the project to appear in the navigation.
    'nav_title': 'ATENXA',

    # Set you GA account ID to enable tracking
    #'google_analytics_account': 'UA-XXXXX',

    # Specify a base_url used to generate sitemap.xml. If not
    # specified, then no sitemap will be built.
    #'base_url': 'https://project.github.io/project',

    # Set the color and the accent color
    'color_primary': 'red',
    'color_accent': 'yellow',

    # Set the repo location to get a badge with stats
    #'repo_url': 'https://github.com/project/project/',
    #'repo_name': 'Project',

    # Visible levels of the global TOC; -1 means unlimited
    'globaltoc_depth': 3,
    # If False, expand all TOC entries
    'globaltoc_collapse': False,
    # If True, show hidden TOC entries
    'globaltoc_includehidden': False,
}

index.rst の設定

indexでなくてもよいのだが、関数とその概要の一覧表を入れたい箇所に

.. automodapi:: atenxa
    :no-inheritance-diagram:

こんなのを書いておく。(TOCtreeと同じ要領である。)

ドキュメントのビルド

./docsで

make clean make html

1行目で./docs/buildを一度きれいに空にして、改めてhtmlをビルドする。

./buildにHTMLなど必要なものが書き出されるので、まとめてFTPでアップすればよい。

f:id:AKAGI-vrmstation:20201013235108p:plain

かなり良くできているSphinx-automodapiであるが、唯一心配なのは、あまりに知名度が低いことである。

参考

sphinx-rtd-tutorial.readthedocs.io

bashtage.github.io

www.sphinx-doc.org

www.sphinx-doc.org