6.1 KiB
Documentation - ドキュメント
📋 概要
Python-Hakorune統合のドキュメント計画です。
📚 ドキュメント構成
1. ユーザーガイド
クイックスタート
# Python統合クイックスタート
## インストール
hakorune-pythonプラグインをインストール:
```bash
cargo build --release --features python-integration
基本的な使い方
// Pythonコードを実行
local py = new PyRuntimeBox()
local result = py.eval("2 + 3")
console.log(result.to_string()) // "5"
// モジュールをインポート
local math = py.import("math")
local pi = math.getattr("pi")
console.log(pi.to_string()) // "3.14159..."
#### チュートリアル
- Python基本操作
- モジュールインポート
- オブジェクト操作
- エラーハンドリング
- パフォーマンス最適化
### 2. リファレンス
#### PyRuntimeBox API
```markdown
# PyRuntimeBox
Python実行環境を提供するBox。
## メソッド
### eval(code: StringBox) -> PyObjectBox
Pythonコードを評価し、結果を返す。
**引数:**
- `code`: 実行するPythonコード
**戻り値:**
- `PyObjectBox`: 実行結果
**例:**
```hakorune
local py = new PyRuntimeBox()
local result = py.eval("2 + 3")
import(name: StringBox) -> PyObjectBox
Pythonモジュールをインポート。
引数:
name: モジュール名
戻り値:
PyObjectBox: インポートされたモジュール
例:
local math = py.import("math")
#### PyObjectBox API
```markdown
# PyObjectBox
Pythonオブジェクトを表すBox。
## メソッド
### getattr(name: StringBox) -> PyObjectBox
オブジェクトの属性を取得。
### setattr(name: StringBox, value: PyObjectBox)
オブジェクトの属性を設定。
### call(args: ArrayBox) -> PyObjectBox
オブジェクトを関数として呼び出し。
### to_string() -> StringBox
Pythonオブジェクトを文字列に変換。
### to_int() -> IntegerBox
Pythonオブジェクトを整数に変換。
### to_bool() -> BoolBox
Pythonオブジェクトを真偽値に変換。
3. 設計ドキュメント
アーキテクチャ
- 全体構成
- レイヤー構造
- データフロー
ABI仕様
- ハンドル管理
- 型変換ルール
- エラーハンドリング
GIL管理
- 獲得・解放ルール
- ネスト呼び出し
- マルチスレッド対応
4. 開発者ガイド
プラグイン開発
# Python統合プラグイン開発ガイド
## プラグインの構造
```rust
// src/lib.rs
use hakorune_plugin_api::*;
#[no_mangle]
pub extern "C" fn nyplug_python_invoke(
method_id: u32,
args: *const TLV,
args_len: usize,
ret: *mut TLV,
) -> i32 {
// 実装
}
ビルド
cargo build --release --crate-type cdylib
#### コントリビューション
- コーディング規約
- テストガイドライン
- プルリクエストプロセス
### 5. トラブルシューティング
#### よくある問題
**Q: Pythonモジュールが見つからない**
A: PYTHONPATHを設定してください: export PYTHONPATH=/path/to/modules:$PYTHONPATH
**Q: GILデッドロックが発生する**
A: ネスト呼び出しを避けるか、GILを明示的に解放してください。
**Q: メモリリークが発生する**
A: PyObjectBoxを適切にdropしているか確認してください。
## 📝 ドキュメント作成タスク
### Phase 1: 基本ドキュメント
- [ ] README.md（概要）
- [ ] QUICKSTART.md（クイックスタート）
- [ ] INSTALLATION.md（インストール）
### Phase 2: API リファレンス
- [ ] PyRuntimeBox API
- [ ] PyObjectBox API
- [ ] 型変換ルール
### Phase 3: チュートリアル
- [ ] 基本操作
- [ ] モジュールインポート
- [ ] オブジェクト操作
- [ ] エラーハンドリング
### Phase 4: 開発者向け
- [ ] アーキテクチャ設計
- [ ] プラグイン開発ガイド
- [ ] コントリビューションガイド
### Phase 5: その他
- [ ] トラブルシューティング
- [ ] パフォーマンスガイド
- [ ] ベストプラクティス
## 🎯 ドキュメント品質基準
### 必須要件
- [ ] コードサンプルが動作する
- [ ] 用語が一貫している
- [ ] エラーメッセージが明確
- [ ] プラットフォーム差異を記載
### 推奨要件
- [ ] 図表を含む
- [ ] ビデオチュートリアル
- [ ] 多言語対応（日本語・英語）
- [ ] 検索可能
## 📊 ドキュメント構成図
docs/ ├── guides/ │ ├── python-integration/ │ │ ├── README.md # 概要 │ │ ├── quickstart.md # クイックスタート │ │ ├── installation.md # インストール │ │ ├── tutorial/ # チュートリアル │ │ │ ├── 01-basics.md │ │ │ ├── 02-modules.md │ │ │ ├── 03-objects.md │ │ │ └── 04-errors.md │ │ └── troubleshooting.md # トラブルシューティング │ └── ... ├── reference/ │ ├── python-integration/ │ │ ├── pyruntimebox-api.md # PyRuntimeBox API │ │ ├── pyobjectbox-api.md # PyObjectBox API │ │ ├── type-conversion.md # 型変換ルール │ │ └── error-handling.md # エラーハンドリング │ └── ... └── development/ └── python-integration/ ├── architecture.md # アーキテクチャ ├── plugin-dev.md # プラグイン開発 └── contributing.md # コントリビューション
## 🔗 関連リソース
### 公式ドキュメント
- [Python C API](https://docs.python.org/3/c-api/)
- [PyO3 Guide](https://pyo3.rs/)
### 参考実装
- Rust PyO3
- Node.js Python bindings
- Julia Python interop
## 🔗 関連ドキュメント
- [Phase 20 メインREADME](../README.md)
- [Planning](../planning/)
- [Core Implementation](../core-implementation/)