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
아스키독 문서 내부로 링크를하고 싶다면 <<TEST DOCS>> 로 이동

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해 화면에 보여준다.