Sphinxで文書をつくりReadthedocsで公開する（前編）

オープンソースソフトウェアプロジェクトがドキュメントを公開するための手段として、Sphinxを使って文書を生成し、Readthedocsによりそれを公開する、という流れは一つの定番として定着しています。

stasmodels ではドキュメントをSphinxのreStructuredTextのフォーマットで作成しているため、現在進めている和訳作業においてもSphinxで文書を生成し、結果はReadthedocsのホスティングサイトで公開しています。

筆者は通常マニュアル的な文書はmarkdownで作成しています。似たところはあるにしてもreStructuredTextはけっこう複雑でなかなか学習意欲が高まらないのですが、文書和訳がなんとかできればOKという割り切りで作業を進めています。

この投稿では、備忘のため作業のおおまかな流れを以下５ステップで整理しておこうと思います。筆者には今回のような作業の経験知が乏しいので、何かもっとスマートなあるいはしっかりした方法をご存じの方からアドバイスいただけると嬉しいです。

1. PC作業環境をつくる

作業用の windows PC にstatsmodelsのプロジェクトをクローンします（参考 statsmodelsのインストール：https://smdocs-jp.readthedocs.io/ja/latest/install.html）。作業は文書の翻訳を行うのが目的なのでソースからの環境ビルドは省略します。

stable版stasmodels（ver 0.14.2）がサポートするpythonは3.8、3.9、および 3.10となっています。そこで3.10の仮想環境をプロジェクトのルートに作成します。あらかじめPCにはpython3の環境を作っておく必要があります。

statsmodels>python -m venv venv

仮想環境をactivateしたあとで、同じフォルダに置かれたrequirements-doc.txtの内容をインストールします。ただし後々のためにいくつか修正を加えておく必要があります。以下が修正後のファイルです。pandasのバージョンを2.0台に、numpyを1.26.4に、そして pytest、patsy、pickleshareを追加インストールします。

# Requirements for doc build, in addition to requirements.txt
sphinx
# Avoid warnings which break Sphinx by pinning pandas
pandas>=2.0,<2.1
numpy==1.26.4
sphinx-immaterial
jupyter
notebook
nbsphinx
nbconvert
pyyaml
pandas-datareader
simplegeneric
seaborn
numpydoc
theano-pymc; os_name != "nt"
pymc3; os_name != "nt"
arviz; os_name != "nt"
jinja2==3.0.3
statsmodels
pytest
patsy
pickleshare

statsmodels>.\venv\Scripts\activate.bat
(venv)statsmodels>pip install -r requirements-doc.txt

いくつかのモジュールがwindwsでは読み込まれないので、これらを使う例題のjupyter notebookの確認はLinuxなど他プラットフォームで行う必要があります。

2. 和訳文書を作成する

この作業のために作業用PC上に、Sphinx ドキュメントサイトを参照してSphinxの環境を作ります。statsmodelsではページデザインのためにsphinx-rtd-themeを使っていますのでこれも併せてインストールしておきます。

(venv)statsmodels>pip install sphinx　sphinx-rtd-theme

また国際化対応（i18n）のためにsphinx-intlというモジュールが必要となります。環境構築については、以下サイトを参考とさせてもらいました。

国際化：　https://www.sphinx-doc.org/ja/master/usage/advanced/intl.html

statsmodelsのドキュメントは statsmodels\docs に全て格納されています。以下の説明では直接このフォルダ配下を翻訳作業用に使う説明をしています。失敗したときのためにdocs配下をバックアップしておきます。

i18nと略称される国際化対応の作業は標準化されていて、次のステップを踏みます。

1. gettextコマンドを使って翻訳対象元文書から翻訳単位のセンテンスを抽出した.potファイルを作成する。
2. .potファイルから翻訳単位のセンテンスと翻訳文をペアにした.poファイルを作成する。
3. .poファイルを編集して翻訳文（今回でいえば和文）を作成する。
4. .poファイルをmsgfmtコマンドを使ってmoファイルへとコンパイルする。

上記参考サイトの記載に従って、source\conf.pyの末尾に次の２行を追加します。

locale_dirs = ['locales\\']　# Mac,Linux では 'locales/'
gettext_compact = False

次にバッチ定義ファイル（make.bat）を確認し、いくつか修正を加えます。

...（略）
REM docs\source をソース格納フォルダとする。
set SOURCEDIR=source  
REM docs\build をビルド結果格納フォルダとする。
set BUILDDIR=build
...（略）
REM "make html"とコマンド入力することで和訳ドキュメントビルドが実行され、htmlとして出力されるようにする。
if "%1" == "html" (
    %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% -D language=ja
)

Sphinxに組み込みのgettextコマンドを使ってpotファイルを生成します。

(venv)statsmodels\docs>sphinx-build -M gettext source build

この処理はかなり時間がかかります。終了すると、source 配下のrstファイルを元にpotファイルが作成され \build\gettext フォルダに配置されます。次にsphinx-intlコマンドを使ってpoファイルを生成します。

(venv)statsmodels\docs>sphinx-intl update -d source/locales -p build/gettext  -l ja

終了すると、source\locales\ja\LC_MESSAGES の下にpoファイルが生成されていることがわかります。今回作業では原則、元の英文ドキュメントは修正しませんので、上記の手続きは今後発生しません。

poファイルの対訳文作成にはpoeditのような専用ツールを使うことが便利です。現在進めている作業は、ある程度対訳文が蓄積されましたら、いよいよ文書のビルドを行い最終的なhtmlの出来具合を確認します。

コマンドプロンプトでmake htmlを実行すると、ビルドプロプロセスが開始されます。初回はけっこう時間がかかります。完了すると build/htmlフォルダの下に完成したhtmlが配置されるのでブラウザで出来具合を確認します。

今回はここまでとします。次回は残る以下の項目について記載する予定です。

3. 和訳文書のためのリポジトリを作成する

4. Readthedocs環境を作成する

5. Readthedocsで文書をビルドし公開する

以上です。