## 특정 상황(예: 내부용 문서만 급하게 뽑아야 할 때)을 위해 **빌드 시점에 제어하는 방법**
그 질문에 대한 답변은 **"반반"**입니다. 기본적으로 `./gradlew asciidoctor`를 실행하면 `sources`에 선언된 파일들을 **한꺼번에** 빌드하도록 설계되어 있습니다.
하지만 특정 상황(예: 내부용 문서만 급하게 뽑아야 할 때)을 위해 **빌드 시점에 제어하는 방법**이 2가지 있습니다.
---
### 1. 프로젝트 속성(`P`)을 이용한 동적 제어 (가장 추천)
명령어 뒤에 `-P` 옵션을 붙여서 빌드할 파일을 직접 지정하는 방식입니다.
**`build.gradle` 설정:**
Gradle
```java
asciidoctor {
sources {
// 프로젝트 속성 'docType'이 들어오면 해당 파일만, 없으면 기본값(index)을 포함
if (project.hasProperty('docType')) {
include "${project.property('docType')}.adoc"
} else {
include 'index.adoc', 'internal.adoc'
}
}
}`
```
**실행 방법:**
- **internal.adoc만 빌드:** `./gradlew asciidoctor -PdocType=internal`
- **전체 빌드:** `./gradlew asciidoctor`
---
### 2. 별도의 Gradle Task로 분리 (구조적 접근)
문서 종류별로 아예 '일(Task)'을 따로 정의하는 방식입니다. 설정은 조금 길지만 나중에 관리하기는 이 방식이 훨씬 명확합니다.
**`build.gradle` 설정:**
Gradle
```java
// 공통 설정 정의
tasks.withType(org.asciidoctor.gradle.jvm.AsciidoctorTask) {
configurations 'asciidoctorExt'
baseDirFollowsSourceFile()
inputs.dir snippetsDir
dependsOn test
}
// 1. 외부 공개용 문서 Task
task publicDoc(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) {
sources { include 'index.adoc' }
outputDir = file("build/docs/public")
}
// 2. 내부 통신용 문서 Task
task internalDoc(type: org.asciidoctor.gradle.jvm.AsciidoctorTask) {
sources { include 'internal.adoc' }
outputDir = file("build/docs/internal")
}`
```
**실행 방법:**
- **내부용만:** `./gradlew internalDoc`
- **외부용만:** `./gradlew publicDoc`
---
### 💡 어떤 방법이 좋을까요?
- **API가 많지 않고 단순히 파일만 분리하고 싶다면:** 1번 방식(`P` 옵션)이 간단합니다.
- **외부용/내부용 문서의 저장 경로가 다르거나, 적용되는 테마(CSS)가 아예 다르다면:** 2번 방식(Task 분리)이 훨씬 강력합니다.
### ⚠️ 주의할 점
`sources` 블록 내에서 `include`를 명시하면, 그 리스트에 없는 파일들은 빌드 대상에서 제외됩니다. 만약 `index.adoc`내부에서 `include::common.adoc[]` 처럼 다른 파일을 불러오고 있다면, 그 **불려가는(Fragment) 파일들은 `sources`에 포함시키지 않아도 됩니다.** (메인 파일만 포함시키면 됩니다.)
댓글
댓글 쓰기