Skip to content

Commit a646a46

Browse files
whitewhite
white
authored and
white
committed
docs: add Maven plugin documentation and example
- Add Maven Quick Start tab to README.md and README.ko.md - Add Maven setup section to docs/quickstart.md - Add Maven example row to docs/examples/index.md - Add new docs/examples/maven-example.md page - Add Maven Example to mkdocs.yml navigation - Add python-embed-examples/maven-example/ with pom.xml and MavenExample.java
1 parent f9bc771 commit a646a46

8 files changed

Lines changed: 329 additions & 46 deletions

File tree

‎README.ko.md‎

Lines changed: 53 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,21 +12,57 @@ PythonEmbed는 서브프로세스 + [MessagePack](https://msgpack.org/) 바이
1212
1313
## 빠른 시작
1414

15-
`build.gradle`에 Gradle 플러그인을 추가하세요:
16-
17-
```groovy
18-
plugins {
19-
id 'io.github.howtis.python-embed' version '1.0.2'
20-
}
21-
22-
pythonEmbed {
23-
packages = ['numpy']
24-
}
25-
26-
dependencies {
27-
implementation 'io.github.howtis:python-embed-runtime:1.0.2'
28-
}
29-
```
15+
=== "Gradle"
16+
17+
`build.gradle`에 Gradle 플러그인을 추가하세요:
18+
19+
```groovy
20+
plugins {
21+
id 'io.github.howtis.python-embed' version '1.0.2'
22+
}
23+
24+
pythonEmbed {
25+
packages = ['numpy']
26+
}
27+
28+
dependencies {
29+
implementation 'io.github.howtis:python-embed-runtime:1.0.2'
30+
}
31+
```
32+
33+
=== "Maven"
34+
35+
`pom.xml`에 Maven 플러그인을 추가하세요:
36+
37+
```xml
38+
<dependencies>
39+
<dependency>
40+
<groupId>io.github.howtis</groupId>
41+
<artifactId>python-embed-runtime</artifactId>
42+
<version>1.0.2</version>
43+
</dependency>
44+
</dependencies>
45+
46+
<build>
47+
<plugins>
48+
<plugin>
49+
<groupId>io.github.howtis</groupId>
50+
<artifactId>python-embed-maven-plugin</artifactId>
51+
<version>1.0.2</version>
52+
<executions>
53+
<execution>
54+
<goals><goal>setup</goal></goals>
55+
</execution>
56+
</executions>
57+
<configuration>
58+
<packages>
59+
<package>numpy</package>
60+
</packages>
61+
</configuration>
62+
</plugin>
63+
</plugins>
64+
</build>
65+
```
3066

3167
이제 Java 코드에서 사용하면 됩니다:
3268

@@ -38,7 +74,7 @@ try (PythonEmbed py = PythonEmbed.create()) {
3874
}
3975
```
4076

41-
Gradle 플러그인이 Python 설치, venv 생성, 패키지 설치를 빌드 시점에 자동으로 처리합니다.
77+
빌드 플러그인이 Python 설치, venv 생성, 패키지 설치를 빌드 시점에 자동으로 처리합니다.
4278

4379
## 주요 기능
4480

@@ -58,6 +94,7 @@ Gradle 플러그인이 Python 설치, venv 생성, 패키지 설치를 빌드
5894
## 모듈
5995

6096
- **[python-embed-gradle-plugin](python-embed-gradle-plugin/)** — venv 생성, 패키지 설치, Python 자동 다운로드
97+
- **[python-embed-maven-plugin](python-embed-maven-plugin/)** — Gradle 플러그인의 Maven 버전
6198
- **[python-embed-runtime](python-embed-runtime/)** — 프로세스 통신, 풀 관리, 타입 변환
6299
- **[python-embed-spring-boot-starter](python-embed-spring-boot-starter/)** — Spring Boot 3.x 자동 구성 (SINGLE/POOL 모드)
63100
- **[python-embed-examples](python-embed-examples/)** — 13가지 실제 예제

‎README.md‎

Lines changed: 53 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -12,21 +12,57 @@ PythonEmbed embeds a real CPython interpreter in your JVM application via a subp
1212
1313
## Quick Start
1414

15-
Add the Gradle plugin to `build.gradle`:
16-
17-
```groovy
18-
plugins {
19-
id 'io.github.howtis.python-embed' version '1.0.2'
20-
}
21-
22-
pythonEmbed {
23-
packages = ['numpy']
24-
}
25-
26-
dependencies {
27-
implementation 'io.github.howtis:python-embed-runtime:1.0.2'
28-
}
29-
```
15+
=== "Gradle"
16+
17+
Add the Gradle plugin to `build.gradle`:
18+
19+
```groovy
20+
plugins {
21+
id 'io.github.howtis.python-embed' version '1.0.2'
22+
}
23+
24+
pythonEmbed {
25+
packages = ['numpy']
26+
}
27+
28+
dependencies {
29+
implementation 'io.github.howtis:python-embed-runtime:1.0.2'
30+
}
31+
```
32+
33+
=== "Maven"
34+
35+
Add the Maven plugin to `pom.xml`:
36+
37+
```xml
38+
<dependencies>
39+
<dependency>
40+
<groupId>io.github.howtis</groupId>
41+
<artifactId>python-embed-runtime</artifactId>
42+
<version>1.0.2</version>
43+
</dependency>
44+
</dependencies>
45+
46+
<build>
47+
<plugins>
48+
<plugin>
49+
<groupId>io.github.howtis</groupId>
50+
<artifactId>python-embed-maven-plugin</artifactId>
51+
<version>1.0.2</version>
52+
<executions>
53+
<execution>
54+
<goals><goal>setup</goal></goals>
55+
</execution>
56+
</executions>
57+
<configuration>
58+
<packages>
59+
<package>numpy</package>
60+
</packages>
61+
</configuration>
62+
</plugin>
63+
</plugins>
64+
</build>
65+
```
3066

3167
Then use it in your Java code:
3268

@@ -38,7 +74,7 @@ try (PythonEmbed py = PythonEmbed.create()) {
3874
}
3975
```
4076

41-
The Gradle plugin handles Python installation, venv creation, and package installation at build time.
77+
The build plugin handles Python installation, venv creation, and package installation at build time.
4278

4379
## Key Features
4480

@@ -58,6 +94,7 @@ The Gradle plugin handles Python installation, venv creation, and package instal
5894
## Modules
5995

6096
- **[python-embed-gradle-plugin](python-embed-gradle-plugin/)** — venv creation, package installation, Python auto-download
97+
- **[python-embed-maven-plugin](python-embed-maven-plugin/)** — Maven equivalent of the Gradle plugin
6198
- **[python-embed-runtime](python-embed-runtime/)** — process communication, pool management, type conversion
6299
- **[python-embed-spring-boot-starter](python-embed-spring-boot-starter/)** — Spring Boot 3.x auto-configuration (SINGLE/POOL modes)
63100
- **[python-embed-examples](python-embed-examples/)** — 13 real-world examples

‎docs/examples/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Examples
22

3-
13 working examples demonstrating PythonEmbed features. Each example is a standalone Gradle subproject you can run directly.
3+
13 working examples demonstrating PythonEmbed features. Each example is a standalone subproject you can run directly.
44

55
## Running Examples
66

@@ -24,6 +24,7 @@ Or run all examples at once (CI):
2424
| [Configuration](configuration.md) | `PythonEmbed.Options` builder, env vars, warmup |
2525
| [Error Handling](error-handling.md) | `PythonExecutionException`, traceback, cause codes |
2626
| [Health Monitor](health-monitor.md) | `ping()`, `health()`, pool monitoring |
27+
| [Maven Example](maven-example.md) | Maven plugin setup, basic eval, numpy |
2728
| [Numpy Basic](numpy-basic.md) | NumPy arrays, operations, broadcasting |
2829
| [Object Handle](object-handle.md) | `ref()`, handle lifecycle, cross-call references |
2930
| [Pandas Dataframe](pandas-dataframe.md) | DataFrame creation, compute, pass to Java |

‎docs/examples/maven-example.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Maven Example
2+
3+
Demonstrates how to use PythonEmbed with the Maven plugin (`python-embed-maven-plugin`).
4+
5+
## What It Shows
6+
7+
- Maven plugin configuration in `pom.xml`
8+
- Auto-venv setup with `python-embed:setup` goal
9+
- Basic `eval()` and `exec()` calls
10+
- NumPy usage via installed packages
11+
12+
## pom.xml
13+
14+
```xml
15+
<dependencies>
16+
<dependency>
17+
<groupId>io.github.howtis</groupId>
18+
<artifactId>python-embed-runtime</artifactId>
19+
<version>1.0.2</version>
20+
</dependency>
21+
</dependencies>
22+
23+
<build>
24+
<plugins>
25+
<plugin>
26+
<groupId>io.github.howtis</groupId>
27+
<artifactId>python-embed-maven-plugin</artifactId>
28+
<version>1.0.2</version>
29+
<executions>
30+
<execution>
31+
<goals><goal>setup</goal></goals>
32+
</execution>
33+
</executions>
34+
<configuration>
35+
<packages>
36+
<package>numpy</package>
37+
</packages>
38+
</configuration>
39+
</plugin>
40+
</plugins>
41+
</build>
42+
```
43+
44+
## Running
45+
46+
```bash
47+
cd python-embed-examples/maven-example
48+
mvn compile exec:java
49+
```
50+
51+
The `setup` goal runs automatically during the `generate-resources` phase, so you don't need to call it manually.
52+
53+
## Source
54+
55+
```java
56+
try (PythonEmbed py = PythonEmbed.create()) {
57+
py.exec("x = 42");
58+
int x = py.eval("x * 2").asInt();
59+
System.out.println("42 * 2 = " + x);
60+
61+
py.exec("import numpy as np");
62+
PythonValue result = py.eval("[int(x) for x in np.linspace(0, 10, 2)]");
63+
System.out.println("numpy.linspace(0, 10, 2): " + result.asList());
64+
}
65+
```
66+
67+
See [Installation](../installation.md) for detailed Maven configuration.

‎docs/quickstart.md‎

Lines changed: 49 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,59 @@
22

33
Get PythonEmbed running in your project in 5 minutes.
44

5-
## 1. Add the Gradle Plugin
5+
## 1. Add the Build Plugin
66

7-
Add to `build.gradle`:
7+
=== "Gradle"
88

9-
```groovy
10-
plugins {
11-
id 'io.github.howtis.python-embed' version '1.0.2'
12-
}
9+
Add to `build.gradle`:
1310

14-
dependencies {
15-
implementation 'io.github.howtis:python-embed-runtime:1.0.2'
16-
}
11+
```groovy
12+
plugins {
13+
id 'io.github.howtis.python-embed' version '1.0.2'
14+
}
1715

18-
pythonEmbed {
19-
packages = ['numpy']
20-
}
21-
```
16+
dependencies {
17+
implementation 'io.github.howtis:python-embed-runtime:1.0.2'
18+
}
19+
20+
pythonEmbed {
21+
packages = ['numpy']
22+
}
23+
```
24+
25+
=== "Maven"
26+
27+
Add to `pom.xml`:
28+
29+
```xml
30+
<dependencies>
31+
<dependency>
32+
<groupId>io.github.howtis</groupId>
33+
<artifactId>python-embed-runtime</artifactId>
34+
<version>1.0.2</version>
35+
</dependency>
36+
</dependencies>
37+
38+
<build>
39+
<plugins>
40+
<plugin>
41+
<groupId>io.github.howtis</groupId>
42+
<artifactId>python-embed-maven-plugin</artifactId>
43+
<version>1.0.2</version>
44+
<executions>
45+
<execution>
46+
<goals><goal>setup</goal></goals>
47+
</execution>
48+
</executions>
49+
<configuration>
50+
<packages>
51+
<package>numpy</package>
52+
</packages>
53+
</configuration>
54+
</plugin>
55+
</plugins>
56+
</build>
57+
```
2258

2359
The plugin automatically downloads Python (if needed), creates a venv, and installs packages at build time.
2460

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ nav:
3838
- Configuration: examples/configuration.md
3939
- Error Handling: examples/error-handling.md
4040
- Health Monitor: examples/health-monitor.md
41+
- Maven Example: examples/maven-example.md
4142
- Numpy Basic: examples/numpy-basic.md
4243
- Object Handle: examples/object-handle.md
4344
- Pandas Dataframe: examples/pandas-dataframe.md

0 commit comments

Comments
 (0)