[Section 3] Asciidoc

Kim·2022년 11월 14일

Boot Camp

목록 보기

48/64

Asciidoc

Asciidoc은 Spring Rest Docs를 통해 생성되는 텍스트 기반 문서 포맷이다.
Asciidoc 포맷을 사용해서 문서, 웹 페이지, 블로그 게시물 등을 작성할 수 있고 Asciidoc 포맷으로 작성된 문서는 HTML, PDF, EPUB, 매뉴얼 페이지를 포함한 다양한 형식으로 변환될 수 있다.

Asciidoc은 주로 기술 문서 작성을 위해 설계된 가벼운 마크업 언어이기도 한다.

목차 구성

= 샘플 애플리케이션     	 // (1)
:sectnums:                  // (2)
:toc: left                  // (3)
:toclevels: 4               // (4)
:toc-title: Table of Contents   // (5)
:source-highlighter: prettify   // (6)

Kim <sample@gmail.com>

v1.0.0, 2022.11.14

문서의 제목을 작성하려면 =를 추가하면 된다. === 같이 개수가 늘어날 수록 글자는 작아진다.
목차에서 각 섹션의 넘버링을 주려면 :sectnums:을 추가하면 된다.
:toc:는 목차를 문서의 어느 위치에 구성할 것인지를 설정한다. 예시 코드에서는 문서의 왼쪽에 목차가 표시되도록 left를 지정했다.
:toclevels:은 목차에 표시할 제목의 level을 지정한다. 예시 코드는 4로 지정해서 ====까지 제목만 목차에 표시된다.
:toc-title: 은 목차의 제목을 지정할 수 있다.
:source-highlighter: 문서에 표시되는 소스 코드 하이라이터를 지정한다. 예시 코드는 prettify를 지정했다.

박스 문단

***     // (1)
Nulla consequat massa quis enim.
 // (2)
 Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.
 Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec,
***

API 문서에 박스 문단을 구성해서 API 문서에 대한 설명을 추가할 수 있다.
1. ***은 단락을 구분할 수 있는 수평선을 추가해준다.
2. 문단의 제목 다음에 한 라인을 띄우고 한 칸 들여쓰기한 문단을 작성하면 박스 문단을 사용할 수 있다.

경고 문구

***
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

 Aenean commodo ligula eget dolor. Aenean massa. 
 Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, 
 ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate
// (1)
CAUTION: Duis leo. Sed fringilla mauris sit amet nibh. Donec sodales sagittis magna.

***

CAUTION을 사용해서 경고 문구를 추가할 수 있다.
이 외에 NOTE: , TIP: , IMPORTANT: , WARNING: 등을 사용할 수 있다.

URL Scheme 자동 인식

다음과 같은 URL Scheme는 Asciidoc에서 자동으로 인식하여 링크가 설정된다.
http, https, ftp, irc, mailto, hgd@gmail.com

이미지 추가

API 문서에 이미지를 추가하려면 image::를 사용해 추가할 수 있다.
image::https://spring.io/images/spring-logo-9146a4d3298760c2e7e49595184e1975.svg[spring]
**

Asciidoctor

Asciidoctor는 Asciidoc 포맷 문서를 파싱하여 HTML 5, 매뉴얼 페이지, PDF 및 EPUB 3 등의 문서를 생성하는 툴이다.

Spring Rest Docs에서는 Asciidoc 포맷의 문서를 HTML 파일로 변환하기 위해 내부적으로 Asciidoctor를 사용한다.
그러므로 Spring Rest Docs를 통해 생성되는 문서 스니핏을 템플릿 문서에 포함해서 하나의 API 문서로 통합하는 방법 정도는 알고 있으면 좋다.

문서 스니핏을 템플릿 문서에 포함

템플릿 문서에 포함된 스닛핏은 애플리케이션 빌드 타임에 내부적으로 Asciidoctor가 index.adoc을 index.html로 변환 후, 특정 디렉토리(src/main/resources/static/docs)에 생성한다.

***
== MemberController
=== 회원 등록
.curl-request       // (1)
include::{snippets}/post-member/http-request.adoc[]    // (2)

.request-fields
include::{snippets}/post-member/request-fields.adoc[]

.http-response
include::{snippets}/post-member/http-response.adoc[]

...

.curl-request에서 .은 하나의 스니핏 섹션 제목을 표현하기 위해 사용한다. curl-request은 섹션의 제목이고 원하는 대로 작성할 수 있다.
include는 Asciidoctor에서 사용하는 매크로 중 하나이다. 스니핏을 템플릿 문서에 포함할 때 사용한다.
::은 매크로를 사용하기 위한 표기법이다.
{snippets}는 해당 스니핏이 생성되는 디폴트 경로를 의미하며, build.gradle 파일에 설정한 snippetsDir 변수를 참조하는데 사용할 수 있다.

⬇ build.gradle 파일


...

ext {
	set('snippetsDir', file("build/generated-snippets"))
}

...

🔑Key Summary

Asciidoc은 Spring Rest Docs를 통해 생성되는 텍스트 기반 문서 포맷이다.
주로 기술 문서 작성을 위해 설계된 가벼운 마크업 언어이기도 하다.
Asciidoc을 이용해서 조금 더 세련되고, 가독성 좋은 API 문서를 만들 수 있다.
Asciidoctor는 AsciiDoc 포맷의 문서를 파싱해서 HTML 5, 매뉴얼 페이지, PDF 및 EPUB 3 등의 문서를 생성하는 툴이다.