spring-asciidoctor-backends 사용해 보기

spring-asciidoctor-backends 소개

spring으로 개발하면 spring documentation을 자주 보게 된다.

https://docs.spring.io/spring-framework/docs/current/reference/html/

이 문서는 asciidoctor를 사용하여 만들어졌다.
java maven에서는 asciidoctor-maven-plugin을 사용하여 문서를 생성한다.

https://asciidoctor.org/

spring-asciidoctor-backends는 asciidoctor-maven-plugin dependency에 추가하는 라이브러리로 spring documentation 생성 시 필요한 몇 가지 기능과 문서 스타일을 제공한다.

이전에 spring-asciidoctor-extensions를 소개한 글을 작성한 적이 있다.

2020.07.17 - [Study/Java] - spring-asciidoctor-extensions 사용해 보기

예전에는 asciidoctor를 확장하여 Spring Doc 문서 생성 시 spring-doc-resources와 spring-asciidoctor-extensions를 사용하였는데 이제 더 이상 사용되지 않고 spring-asciidoctor-backends로 교체되었다.
(2023-07-29 추가. spring-asciidoctor-extensions도 계속 릴리즈 되고 있다. 위 정보는 잘못된 정보이다.)

https://github.com/spring-io/spring-asciidoctor-backends

GitHub - spring-io/spring-asciidoctor-backends: A backend for Asciidoctor used to produce Spring styled HTML

spring-asciidoctor-backends는 현재 아래와 같은 기능을 제공하고 있다.

• Spring Look and Feel : 스프링 문서 스타일의 ui 제공
• Responsive Design : 반응형 디자인 제공
• Graceful Javascript Degradation : javascript 비활성화 시에도 올바르게 렌더링 처리
• "Back to Index" Link : 인덱스로 돌아가기 링크 기능 제공
• dark mode 지원
• copy to clipboard  : 코드 부분 복사하기 제공
• Tabs : 소스 부분 탭 선택 기능 (java/kotlin 버전의 코드 제공과 같이 여러 언어 case 제공 시 소스 코드 탭 선택 기능)
• Code Folding : 코드 내 접고 펼치기
• Code Chomping : 코드 내 설명 부분 주석 작성 시 문법 오류 방지
• Anchor Rewriting : 문서 내 링크 변경 시 이전 링크 유지 기능
• Convention Based Code Import : code snippet 호출 주소 축약 제공
• Font Awesome Support : font awesome 이모티콘 사용 제공 용도이나 실제로 제공을 하지 않고 Antora 사용 관련 기능이라고 함

설정하기

asciidoctor-maven-plugin 설정에 spring-asciidoctor-backends 설정을 추가하면 된다.

<plugin>
	<groupId>org.asciidoctor</groupId>
	<artifactId>asciidoctor-maven-plugin</artifactId>
	<version>2.1.0</version>
	<executions>
		<execution>
			<id>generate-html-documentation</id>
			<phase>prepare-package</phase>
			<goals>
				<goal>process-asciidoc</goal>
			</goals>
			<configuration>
				<backend>spring-html</backend>
			</configuration>
		</execution>
	</executions>
	<dependencies>
		<dependency>
			<groupId>io.spring.asciidoctor.backends</groupId>
			<artifactId>spring-asciidoctor-backends</artifactId>
			<version>${spring-asciidoctor-backends.version}</version>
		</dependency>
	</dependencies>
</plugin>

기존 spring-doc-resources는 다운로드하여 압축을 푸는 설정이나 dependency 설정을 해야 했는데 spring-asciidoctor-backends로 넘어오면서 사용하는 게 간편해졌다.

기존 프로젝트 package와 별도로 수행해야 하기 때문에 별도 profile을 지정해 준다.

<profiles>
	<profile>
        <id>asciidoctor</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.asciidoctor</groupId>
                    <artifactId>asciidoctor-maven-plugin</artifactId>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

(만약 spring-restdocs를 사용한다면 위 설정에서 maven-resources-plugin 같은 설정이 더 필요하다.)

문서 작성하기

기본 문서 위치는 `${basedir}/src/docs/asciidoc`이다.

(내 경우 `src/main/asciidoc` 위치로 설정하였음)

해당 위치에 adoc 문서를 적절하게 작성을 한다.

asciidoctor 작성 시 사용하는 문법은 asciidoctor documentation에서 참고하면 된다.

https://asciidoctor.org/docs/

문서 생성하기

내 경우 maven profile에 asciidoctor라고 지정하였기 때문에 다음과 같이 실행하면 asciidoctor plugin이 실행된다.

mvn clean package -P asciidoctor

문서 출력 위치에 대해 별도 설정을 하지 않았다면 기본 위치인 '${project.build.directory}/generated-docs' 위치에 생성이 된다.

스프링이 제공하는 문서와 동일한 ui로 문서가 생성이 된다.