make_sphinx_files.py 技術ドキュメント

プログラムの動作

make_sphinx_files.py は、PythonスクリプトのSphinxドキュメント生成プロセスを自動化し、効率化するためのユーティリティスクリプトです。特定のPythonスクリプトを対象として、以下の主要な機能を提供します。

  • Docstringの自動追加: 外部スクリプト add_docstring.py を利用し、指定されたPythonスクリプトの関数、クラス、メソッドにDocstringを自動で生成・追加します。

  • プログラム解説の自動生成: 外部スクリプト explain_program5.py を利用し、指定されたPythonスクリプトの概要や動作原理に関する解説を生成します。

  • Sphinx用ファイルの生成: Sphinxドキュメントの構造に必要な __init__.py、index.template、[スクリプト名]_index.rst、[スクリプト名]_api.rst などのファイルを自動的に作成します。

  • 実行例ファイルの作成: プログラムの実行例を記述するためのMarkdownファイル ([スクリプト名]_examples.md) のテンプレートを作成します。このテンプレートには、対象スクリプトの --help 出力や、同一ディレクトリ内で検出された関連する画像・データファイルへの参照が自動的に埋め込まれます。

  • ファイルのバックアップと置換: Docstring追加前の元のスクリプトファイルをバックアップし、Docstringが追加された新しいバージョンのスクリプトで元のファイルを置き換えます。

このスクリプトは、Sphinxを用いたPythonプロジェクトのドキュメント作成において、手動でのファイル作成、Docstringやプログラム解説の記述にかかる手間を大幅に削減し、ドキュメントの整合性を維持することを目的としています。

原理

make_sphinx_files.py は、数式や物理式を直接使用していませんが、以下のアルゴリズムと仕組みに基づいて動作します。

  • 外部スクリプトの呼び出し: subprocess モジュールを使用して、add_docstring.py および explain_program5.py というAIを活用したドキュメント生成スクリプトを呼び出します。これにより、Docstringの追加やプログラム解説の生成といった複雑なタスクを外部に委譲します。

  • Sphinx RSTファイル生成:

    • [スクリプト名]_index.rst: Sphinxの .. toctree:: ディレクティブを使用して、usage、examples、api の各ドキュメントへのリンクを定義します。

    • [スクリプト名]_api.rst: .. automodule:: ディレクティブを使用して、指定されたPythonモジュールのAPIドキュメント（関数、クラス、メソッドのDocstringなど）をSphinxが自動的に抽出し、整形できるように構成します。currentmodule ディレクティブでモジュールパスを設定します。

  • 実行例テンプレートの生成:

    • 対象スクリプトを python [スクリプト名].py --help として実行し、その標準出力と標準エラー出力をキャプチャしてMarkdownファイルに埋め込みます。これにより、コマンドライン引数の説明を自動的にドキュメントに含めることができます。

    • os.listdir を使用して、スクリプトが実行されるカレントディレクトリ内のファイルを走査し、対象スクリプト名で始まり、かつ特定の拡張子 (.png, .jpg, .jpeg, .csv, .xlsx, .xls, .txt) を持つファイルを自動検出します。検出されたファイルは、Markdown形式で実行例ファイル内にリストアップされ、画像ファイルの場合は ![alt_text](path) 形式で埋め込み表示されます。

  • モジュールパスの解決: コマンドライン引数 --subdir が指定されていない場合、relative_from_source 関数が、入力ファイルパスから source ディレクトリ以降の相対パスを抽出し、Sphinxドキュメント内のモジュールパスとして利用します。これは、Sphinxプロジェクトの典型的なディレクトリ構造（例: docs/source/my_module/my_script.py）に対応するためのものです。

  • ファイル操作: os および shutil モジュールを使用して、ファイルの存在チェック、作成、書き込み、コピー、リネームといった操作を行い、ドキュメント生成の一連のプロセスを管理します。

必要な非標準ライブラリとインストール方法

make_sphinx_files.py プログラム自体はPythonの標準ライブラリのみを使用しており、直接的な非標準ライブラリの依存関係はありません。 しかし、本プログラムが呼び出す外部スクリプトや、最終的なSphinxドキュメントのビルドには以下の非標準ライブラリが必要です。

  • Sphinx: ドキュメントの生成ツール本体。

    pip install sphinx

  • OpenAI API クライアントライブラリ: add_docstring.py や explain_program5.py が --api openai または --api openai5 オプションでOpenAIモデルを利用する場合に必要です。

    pip install openai

  • Google Generative AI クライアントライブラリ: add_docstring.py や explain_program5.py が --api google または --api gemini オプションでGoogle Geminiモデルを利用する場合に必要です。

    pip install google-generativeai

必要な入力ファイル

make_sphinx_files.py を実行するために、以下の入力ファイルが必要です。

  1. 対象となるPythonスクリプトファイル:

    • 形式: 任意のPythonスクリプト（.py 拡張子）。

    • データ構造: 通常のPythonコード。このスクリプトは、このファイルにDocstringを追加したり、解説を生成したり、APIドキュメントの基盤とします。

    • 例: my_program.py

  2. add_docstring.py:

    • 形式: Pythonスクリプト。

    • 内容: 対象PythonスクリプトにDocstringを自動追加する機能を持つプログラム。

    • 場所: make_sphinx_files.py と同じディレクトリに配置されている必要があります。

  3. explain_program5.py:

    • 形式: Pythonスクリプト。

    • 内容: 対象Pythonスクリプトの解説を自動生成する機能を持つプログラム。

    • 場所: make_sphinx_files.py と同じディレクトリに配置されている必要があります。

  4. オプション: 関連する画像ファイル:

    • 形式: .png, .jpg, .jpeg などの画像ファイル。

    • 命名規則: 対象Pythonスクリプトのベース名（例: my_program）で始まり、アンダースコア _ の後に続くファイル名（例: my_program_result.png, my_program_chart.jpg）。

    • 場所: 対象Pythonスクリプトと同じディレクトリ。

    • 目的: 生成される [スクリプト名]_examples.md に自動的にリンクまたは埋め込まれます。

  5. オプション: 関連するデータファイル:

    • 形式: .csv, .xlsx, .xls, .txt などのデータファイル。

    • 命名規則: 対象Pythonスクリプトのベース名（例: my_program）で始まり、アンダースコア _ の後に続くファイル名（例: my_program_input_data.csv, my_program_output.txt）。

    • 場所: 対象Pythonスクリプトと同じディレクトリ。

    • 目的: 生成される [スクリプト名]_examples.md に自動的にリンクされます。

生成される出力ファイル

make_sphinx_files.py の実行により、以下のファイルが生成または更新されます。

  1. __init__.py

    • 内容: 空のファイル。Pythonがそのディレクトリをパッケージとして認識するために必要です。

    • 場所: プログラム実行時のカレントディレクトリ。

  2. index.template

    • 内容: Sphinxプロジェクト全体の index.rst に、カレントディレクトリのドキュメント（例: my_program_index）を含めるための参照を記述したテンプレートファイル。既に存在する場合は追記されます。

    • 場所: プログラム実行時のカレントディレクトリ。

  3. [スクリプト名]_index.rst

    • 内容: 特定のPythonスクリプトに関するSphinxドキュメントのトップページ。[スクリプト名]_usage、[スクリプト名]_examples、[スクリプト名]_api へのリンクが含まれます。

    • 場所: プログラム実行時のカレントディレクトリ。

    • 例: my_program_index.rst

  4. [スクリプト名]_api.rst

    • 内容: Sphinxの automodule ディレクティブを使用して、対象PythonスクリプトのAPIドキュメント（関数、クラス、メソッドのDocstringなど）を自動生成するためのファイル。

    • 場所: プログラム実行時のカレントディレクトリ。

    • 例: my_program_api.rst

  5. [スクリプト名]_examples.md

    • 内容: 対象Pythonスクリプトの実行例を記述するためのMarkdownテンプレートファイル。プログラムの --help 出力、検出された関連画像ファイルへの埋め込み表示、検出された関連データファイルへのリンクが自動的に含まれます。

    • 場所: プログラム実行時のカレントディレクトリ。

    • 例: my_program_examples.md

  6. [スクリプト名]_docstring.py (一時ファイル)

    • 内容: add_docstring.py の実行によって生成される、Docstringが追加された一時的なPythonスクリプトファイル。

    • 場所: プログラム実行時のカレントディレクトリ。

    • 備考: このファイルは最終的に元の入力ファイル ([スクリプト名].py) にリネームされ、元の入力ファイルはバックアップされます。その後、このファイル自身は空のダミーファイルとして残されます。

  7. [スクリプト名]_[YYYYMMDD].py

    • 内容: 元の入力Pythonスクリプトファイル ([スクリプト名].py) のバックアップ。Docstring追加前の状態を保持します。YYYYMMDD は実行日の日付です。

    • 場所: プログラム実行時のカレントディレクトリ。

    • 例: my_program_20231027.py

  8. [スクリプト名].py (更新されるファイル)

    • 内容: 元の入力Pythonスクリプトファイルが、Docstringが追加された新しいバージョンに置き換えられます。

コマンドラインでの使用例 (Usage)

make_sphinx_files.py は、以下の書式でコマンドラインから実行します。

python make_sphinx_files.py <infile> [--subdir <subdir>] [--api <api>] [-u <update>] [-w <overwrite>] [-p <pause>]

引数

  • <infile> (必須)

    • 対象となるPythonスクリプトファイル名。

    • 例: my_program.py

  • --subdir <subdir> (オプション)

    • source ディレクトリからの相対パスを指定します。Sphinxのモジュールパス (.. automodule::) を構築する際に使用されます。

    • 指定しない場合、入力ファイルのパスから source ディレクトリ以下の相対パスが自動的に推測されます。

    • 例: my_project.sub_module

  • --api <api> (オプション)

    • add_docstring.py および explain_program5.py で使用するAIサービスを指定します。

    • 選択肢: openai, openai5, google, gemini

    • デフォルト値: google

  • -u, --update <update> (オプション)

    • 更新モードを制御する整数値。add_docstring.py および explain_program5.py に渡されます。

    • デフォルト値: 1

  • -w, --overwrite <overwrite> (オプション)

    • 上書きモードを制御する整数値。add_docstring.py および explain_program5.py に渡されます。

    • デフォルト値: 0

  • -p, --pause <pause> (オプション)

    • プログラムの途中で一時停止するかどうかを制御する整数値。add_docstring.py および explain_program5.py に渡されます。

    • デフォルト値: 0

コマンドラインでの具体的な使用例

ここでは、my_program.py という名前のPythonスクリプトを対象として、make_sphinx_files.py を実行する具体的な例を示します。

まず、作業ディレクトリに以下のファイルが存在すると仮定します。

  • make_sphinx_files.py

  • add_docstring.py

  • explain_program5.py

そして、対象となるPythonスクリプト my_program.py の内容は以下の通りとします。

# my_program.py

import argparse

def greet(name):
    print(f"Hello, {name}!")

def main():
    parser = argparse.ArgumentParser(description="A simple greeting program.")
    parser.add_argument("name", help="The name to greet.")
    args = parser.parse_args()
    greet(args.name)

if __name__ == "__main__":
    main()

また、my_program_chart.png という画像ファイルと my_program_data.csv というデータファイルが同じディレクトリにあるとします。

実行コマンド

Google Gemini API を使用してドキュメントを生成する場合のコマンドは以下のようになります。

python make_sphinx_files.py my_program.py --api google

実行結果の説明

上記のコマンドを実行すると、以下のような処理が順次実行されます。

  1. 引数の表示:

    Args:
  infile='my_program.py'
  subdir=''
  api='google'
  update=1
  overwrite=0
  pause=0

  2. 初期ファイルの作成/更新:

    • __init__.py が作成されます。

    • index.template が作成または更新され、my_program_index が追記されます。

    • my_program_index.rst が作成され、my_program_usage、my_program_examples、my_program_api へのリンクが記述されます。

    • my_program_api.rst が作成され、my_program モジュールのAPIドキュメントを自動生成するための設定が記述されます。

    • my_program_examples.md が作成されます。このファイルには my_program.py --help の出力が埋め込まれ、my_program_data.csv へのリンク、および my_program_chart.png の埋め込み表示が含まれます。

      # my_program 実行例

## help出力 `my_program.py --help`

<pre style="background-color: #f4f4f4; border: 1px solid #ccc; padding: 10px; border-radius: 5px; font-family: 'Courier New', Courier, monospace; overflow-x: auto;">
usage: my_program.py [-h] name

A simple greeting program.

positional arguments:
  name        The name to greet.

options:
  -h, --help  show this help message and exit
</pre>

## データファイル
- [my_program_data.csv](./my_program_data.csv)

## 画像ファイル

- [my_program_chart.png](./my_program_chart.png)
![my_program_chart.png](./my_program_chart.png)

  3. 外部スクリプトの実行:

    • explain_program5.py が my_program.py に対して実行され、その解説が生成されます（通常は別のファイルに出力されるか、コンソールに表示されます）。

    • add_docstring.py が my_program.py に対して実行され、Docstringが自動的に追加された my_program_docstring.py が生成されます。

  4. ファイルのバックアップと置換:

    • 元の my_program.py が my_program_YYYYMMDD.py (例: my_program_20231027.py) としてバックアップされます。

    • my_program_docstring.py の内容が my_program.py に上書きされます。これにより、my_program.py にDocstringが追加された状態になります。

    • my_program_docstring.py は空のダミーファイルとして残されます。

最終的に、カレントディレクトリには以下のファイルが生成・更新されます。

  • __init__.py

  • index.template

  • my_program_index.rst

  • my_program_api.rst

  • my_program_examples.md

  • my_program_docstring.py (空のファイル)

  • my_program_YYYYMMDD.py (元の my_program.py のバックアップ)

  • my_program.py (Docstringが追加されたバージョンに更新済み)

  • my_program_chart.png (変更なし)

  • my_program_data.csv (変更なし)

これらのファイルを使用して、Sphinxでドキュメントをビルドする準備が整います。