docs: restore docs/private/roadmap from 7b4908f9 (Phase 20.31)
This commit is contained in:
nyash-codex
@ -0,0 +1,270 @@
|
||||
# Documentation - ドキュメント
|
||||
|
||||
## 📋 概要
|
||||
|
||||
Python-Hakorune統合のドキュメント計画です。
|
||||
|
||||
## 📚 ドキュメント構成
|
||||
|
||||
### 1. ユーザーガイド
|
||||
|
||||
#### クイックスタート
|
||||
```markdown
|
||||
# Python統合クイックスタート
|
||||
|
||||
## インストール
|
||||
|
||||
hakorune-pythonプラグインをインストール:
|
||||
```bash
|
||||
cargo build --release --features python-integration
|
||||
```
|
||||
|
||||
## 基本的な使い方
|
||||
|
||||
```hakorune
|
||||
// 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`: インポートされたモジュール
|
||||
|
||||
**例:**
|
||||
```hakorune
|
||||
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. 開発者ガイド
|
||||
|
||||
#### プラグイン開発
|
||||
```markdown
|
||||
# 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 {
|
||||
// 実装
|
||||
}
|
||||
```
|
||||
|
||||
## ビルド
|
||||
|
||||
```bash
|
||||
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/)
|
||||
Reference in New Issue
Block a user