TadaoYamaokaの開発日記

個人開発しているスマホアプリや将棋AIの開発ネタを中心に書いていきます。

GPT4を使ってcshogiにドキュメントを追加

cshogi GPT4

オープンソースで開発しているPythonの将棋ライブラリcshogiにドキュメントを追加した。

tadaoyamaoka.github.io

今まで、READMEと強い将棋ソフトの創り方に主要な部分のみ説明を記載しているくらいで、詳細なドキュメントがなかった。

今回、全体的にコードにdocstringを追加して、Sphinx+autodocでドキュメントを生成した。

GPT4でdocstringを生成

docstringの内容は、GPT4を活用して記述した。
GPT4は、ソースの意図をくみ取って、自分で書くよりも適切な説明文を生成してくれた。
GPT4は、将棋の知識や、USIプロトコルに関する知識も持っているらしく、ソースからコンテキストをくみ取ってくれた。

プロンプト

基本は、以下のプロンプトを使用した(Cythonのコードの場合は、Pythonの部分をCythonにした)。

以下のPythonのコードにreStructuredText形式のdocstringを英語で追加してください。
###
def move_to(int move):
    return __move_to(move)
...

以下のようにdocstringが追加される。

def move_to(int move):
    """
    Extract the destination square of a move.

    :param move: A move represented as an integer.
    :type move: int
    :return: The destination square of the move.
    :rtype: int
    """
    return __move_to(move)

たまにreStructuredText形式にならないときや、コードが長いと途中が省略さえることがあったので、「reStructuredText形式にしてください。」や「残りのメソッドも出力してください。」と追加指示を行った。

前提知識を与えたい場合は、「Boardは将棋の盤面を表すクラスです。bodは、局面図(BOD)を表します。」といった情報をプロンプトに追加すると、docstringに反映してくれる。

Sphinx

docstringからドキュメントを生成するために、Sphinxを使用した。
Sphinxは、Pythonのドキュメント生成のデファクトになっている。

手順

以下のように、sphinx-apidocで、定義を出力して、conf.pyで設定を行い、sphinx-buildでhtmlを生成する。

sphinx-apidoc -f -o ./docs .
sphinx-build ./docs/ ./docs/_build/
conf.py

docsディレクトリからソースディレクトリへの相対パスを環境変数に追加する必要がある。

import os
import sys

sys.path.insert(0, os.path.abspath(".."))

docstringからドキュメントを自動生成するために拡張機能を追加する。他にもRead the Docsスタイルや、GitHubPagesのための拡張も追加している。

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx.ext.todo",
    "sphinx.ext.napoleon",
    "sphinx_rtd_theme",
    "sphinx.ext.githubpages",
]

型の情報は、型ヒントから生成するようにする。

autodoc_typehints = "description"
Cythonのコードのドキュメント

Cythonのコードのdocstringは、そのままだと出力されなかったため、対応が必要だった。

.pyxのソースコードには、Pythonコードと同じようにdocstringを記述する。
Sphinxは、.pyxのソースは直接は扱えないため、一旦ビルドする必要がある。

以下のように、手動で.rstにビルドしたモジュールを追加することで出力されるようになる。

cshogi._cshogi module
-----------------

.. automodule:: cshogi._cshogi
   :members:
   :undoc-members:
   :show-inheritance:

cshogiの場合、cshogiのパッケージのデフォルトのモジュールとして使えるように、cshogi/__init__.pyに、Cythonのモジュールをimportしている。
そのため、Cythonのモジュールを.rstに追加せずに、__init__.pyからドキュメントを生成したい。
しかし、__init__.pyでimportを行っただけだと、ドキュメントが生成されないため、__all__にエクスポートするシンボルを記述する必要があった。
モジュールのシンボルをすべて列挙するには、dirを使用して、dir(cshogi._cshogi)のようにして出力すればよい。

cshogi/cshogi/__init__.py at master · TadaoYamaoka/cshogi · GitHub

まとめ

cshogiのソースにGTP4を活用してdocstringを追加し、Sphinx+autodocでドキュメントを生成した。
GTP4は、ソースの内容を理解して、適切な説明文を生成してくれた。
今回docstringを英語で記述したが、英語力はGPT4の方が圧倒的に高いので、docstringは自分で書くよりGPT4に書かせた方がよい。