AsciiDoctor 문법

AsciiDoctor 문법

1. 소개

AsciiDoctor 이란?

JUNIT TEST 이후 만들어진 snippets(.adoc)파일들과 설명을

간단한 명령어들을 통해 HTML으로 변환해준다.

AsciiDctor 사용 이유

API를 서비스 한다면, 사용자를 위한 명세서(문서) 작업이 필요하다.

-> JUNIT TEST 코드를 기반으로 자동으로 가독성 좋은 문서화 작업이 가능하다.

(비교) Asciidoctor vs Markdown

-> Markdown 이 작성하기 편하지만 Include 가 되지 않은 단점이 있습니다.

Slate 를 사용하면 가능하다고 하지만 결과물이 우리가 생각한 doc 파일과는 다르며 별도 설정을 해야하는 번거로움이 있습니다. 따라서 AsciiDoctor가 유리하다고 판단.

설정 방법

/src/docs/asciidoc/api-docs.adoc 파일을 생성한다.

gradle설정으로 html소스 생성이후 html파일 복사하도록 설정

사용법( 예제 + 문법 )

생성된 예제파일 (api-docs.html)

api-docs.html 0.04MB

예제 (api-docs.adoc)

:doctype: book :icons: font :source-highlighter: highlightjs :toc: left :toclevels: 3 :sectlinks: == TEST DOCS *빈행이* __문단으로__ `구분하게` #된다.# [%hardbreaks] 위 내용 작성시 자동 + 효과 https://narusas.github.io/2018/03/21/Asciidoc-basic.html \https://narusas.github.io/2018/03/21/Asciidoc-basic.html 아스키독 문서 내부로 링크를하고 싶다면 <> 로 이동 Dairy:: * Milk * Eggs //- [upperroman] . a . b TIP: 팁입니다 IMPORTANT: 중요합니다. .블럭1 ---- 블럭생성 ---- [%header%autowidth] |=== | 코드 | 내용 | 40 | 성공 |=== [#img-sunset] .reference [link=https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/] image::sunset.jpg[Sunset,100,100] == 상품 == 상품 등록 include::{snippets}/product-controller-test/regist/http-request.adoc[] === request include::{snippets}/product-controller-test/regist/request-fields.adoc[] === response include::{snippets}/product-controller-test/regist/http-response.adoc[]

:toc: left :toclevels: 3 :sectlinks:

== 으로 작성한 섹션별 목차/링크를 자동으로 생성 ( left에 3 depth만큼 표현 )

= , ==, === 으로 섹션 제목을 설정하고 계층을 나눌 수 있다.

사용된 이름은 <<<이름>>> 내용을 통해 이동링크를 설정 할 수 있다.

문단 맨 뒤에 +를 작성해야 개행이 되지만, [%hardbreaks] 사용시 아래 문단은 enter → 개행 처리된다

Dairy:: * Milk * Eggs

해당 단어에 대한 설명을 기입할 수 있다.

[upperroman] . a . b

로마숫자로 자동 표현된다. ( 1씩 증가)

TIP: 팁입니다 IMPORTANT: 중요합니다.

코멘트를 달 때 이미지와 함께 표현할 수 있다.

.블럭1 ---- 블럭생성 ----

모든 문단에 .이름을 통해 제목을 표현할 수 있고, ----을 통해 블럭생성할 수 있다.

[%header%autowidth] |=== | 코드 | 내용 | 40 | 성공 |===

테이블을 만드는법 + %header (1행을 강조) + %autowidth (문자열의 크기만큼 셀 크기 설정)

[#img-sunset] .reference [link=https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/] image::sunset.jpg[Sunset,100,100]

이미지 삽입

include::{snippets}/product-controller-test/regist/http-request.adoc[]

Spring-Docs로 만든 snippet의 경로를 읽어와 include해 화면에 보여준다.

from http://code-resting.tistory.com/16 by ccl(A) rewrite - 2021-02-09 19:01:18