[SpringRestDocs] Unresolved directive in index.adoc-...

모든 테스트 코드가 성공적으로 마치고 

src - docs - asciidoc 하위의 index.adoc 문서에는 미리보기를 했을 때 스니펫이 잘 적용 되었는데, 

build 후에 build - docs - asciidoc 하위의 html에서는 사진과 같은 식으로 모든 스니펫에 Unresolved directive in index.adoc - include::스니펫 오류가 발생했다.

 

 

이는 생성된 스니펫 경로를 읽어오지 못해 발생하는 문제였는데 몇차례 구글링 끝에 index.adoc에 밑과 같은 코드를 추가한 후에야 정삭 작동이 되었다.

ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]

 

코드를 추가한 후에 문제가 해결된 이유는 Asciidoctor에서 {snippets}변수를 정의하지 않았던 문제 때문인 거 같다. 

 

 

왜 이런 문제가 발생했는가?

1. {snippets} 변수 미정의:
   • Asciidoctor는 {snippets} 변수를 사용하는데, 이를 build.gradle에서 설정했더라도 Asciidoctor 자체에서 정의되지 않았다면 index.adoc 파일에서 include::{snippets}/...와 같은 경로가 제대로 해석되지 못한다.
   • ifndef는 해당 변수가 정의되지 않았을 때만 변수를 설정하도록 하여 문제가 발생하지 않게 한다.
2. 환경 의존성:
   • build.gradle에서 snippetsDir을 정의하고 있어도, 이 설정이 Asciidoctor로 제대로 전달되지 않았거나, Asciidoctor가 이를 알지 못한 경우이다. 이는 Asciidoctor와 Gradle의 설정 간 연동 문제로 인해 발생할 수 있다.
3. 경로 설정 문제:
   • Asciidoctor는 include 지시어를 사용할 때 경로를 기준으로 파일을 찾는다. 그러나 {snippets} 변수가 미정의 상태라면 경로를 정확히 해석하지 못해 include file not found 오류가 발생한다.

 

이 코드가 해결하는 방식

1. ifndef와 endif로 조건부 설정:
   • ifndef::snippets[]는 Asciidoctor가 {snippets} 변수를 정의하지 않은 경우에만 이를 설정하도록 한다.
   • 이미 다른 경로에서 {snippets} 변수가 정의되어 있더라도, 중복 정의로 인한 오류를 방지한다.
2. :snippets:로 기본 경로 정의:
   • :snippets:를 통해 {snippets} 변수를 ./build/generated-snippets로 명시적으로 설정한다.
   • 이로 인해 include::{snippets}/...는 ./build/generated-snippets/...로 해석된다.
3. 문서의 독립성 보장:
   • 이 설정을 추가하면 Gradle과의 의존 없이 Asciidoctor가 독립적으로 {snippets} 변수를 사용할 수 있게 된다. 따라서 asciidoctor 작업을 실행할 때 별도의 외부 설정 없이도 올바른 경로를 참조한다.