概要
ドキュメント書くの面倒くさいですよね。記述したコードのサブルーチンや関数、モジュールにドキュメントを書く意義はわかりますが、とても面倒な作業であることには変わりません。そんな面倒くさがり屋のためにChatGPTでドキュメントを自動生成するためのPythonアプリケーション、AutoDogを作りました。
対応言語
以下の言語に対応しています。
- Fortran
- Python
このアプリケーションを作ろうと思った発端が、私が開発しているFortranの流体シミュレーションフレームワークにあるため、Fortranへのドキュメント生成にも対応しています。
使い方
AutoDogはPython 3.9以上で動作します。依存ライブラリはopenaiだけです。
将来変更される可能性が高いですが、今のところ以下のコードを書けばyour_code.f90に記述されたすべての関数やクラスに対しドキュメントを生成してくれます。
import autodog
code = autodog.code('your_code.f90')
engine = autodog.engine(api_key='YOUR-API-KEY')
# insert code documents to a function, class, module, ...
code.insert_docs(engine)
# overwrite your_code.f90
code.write()
Pythonコードに対してドキュメント生成したい場合は、以下のようにautodog.code(…)でPythonファイルを指定すれば大丈夫です。
code = autodog.code('your_code.py')
なお、デフォルトパラメータではChatGPTの'gpt-3.5-turbo'にてdocstring（のような）ドキュメントを生成します。また、OpenAIのAPI利用にはAPI Keyの発行が必須です（有料）。API KeyをOpenAIのサイトで生成し、autodog.engine(api_key='YOUR-API-KEY')で指定してください。
作例
レシピ
ChatGPTのモデルを指定したい
autodog.engine(…)のmodel引数で以下のように指定できます。
engine = autodog.engine(api_key='YOUR-API-KEY', model='gpt-4')
指定可能なモデルはOpenAI API ReferebceのModel endpoint compatibilityより確認できます。End pointは/v1/chat/completionsのみ対応しています。
docstringぽくないドキュメントを生成したい
Fortranコードのドキュメント生成時に発生する需要かと思います。以下のようにautodog.engine(…)のdoc_type引数である程度制御可能です。
engine = autodog.engine(api_key='YOUR-API-KEY', doc_type='document')
デフォルトではdoc_type='docstring'となっており、Fortranでもdocstringのようなドキュメントが生成されます。
既存のドキュメントを上書きしたい
code.insert_docs(engine, overwrite=True)
他のファイルに出力したい
code.write(filepath='other_file.f90')
ドキュメント生成処理解説
AutoDogでは以下のようにドキュメント生成を行います。
- 入力されたコードをパースし、抽象構造木(AST)を作成
- ASTの各関数、クラス、モジュール等ノードを取り出し、各ノードごとにOpenAI APIへ投げる
- APIレスポンスからドキュメントを抽出し、各ノードの適切な位置に挿入
- ASTをアンパースし、ファイルに書き込み
Pythonの場合、標準ライブラリーにASTモジュールがあるためASTは簡単に作れます。Fortranの場合はfparseやlfortranを使えば生成できますが、今回の環境・目的では使用しにくいと感じたためフルスクラッチしています。（使い方わからんかった）
また、ChatGPTからのレスポンスにドキュメント以外の情報があると面倒なので、ドキュメントだけを返答するようプロンプトを工夫しています。
課題
関数やクラスによって生成されるドキュメントのフォーマットがバラバラ
特にFortranのコードで起こる問題ですが、docstringぽく生成されたり、よく見るFortran屋さんのドキュメントらしく生成されたりとフォーマットがバラバラです。この問題はautodog.engine(api_key='YOUR-API-KEY', doc_type='document')としても発生します。
プロンプトのやり方を改善する必要を感じています。
生成されたコメントの整形
ChatGPTが生成するドキュメントは1文の途中で改行することがないので、AutoDog側で整形するようにしていますが、整形結果が美感に少し反しています。こちらも要修正項目だと感じています。
最後に
ChatGPTでドキュメントを自動生成するためのPythonアプリケーション、AutoDogを作ってみました。要改善な項目も多く、ろくにテストもしていないので、今後も修正を続けたいと思っています。興味がありましたら使っていただけると幸いです。