Spring은 모든 프로젝트가 reference 문서를 제공하고 있다.
이 문서가 어떻게 만들어지는지 궁금할 사람들을 위해 소개해본다.
다만 자세한 사용법을 설명하기엔 양이 너무 많기 때문에 링크를 통해 각각의 자세한 설명을 참조해야 한다.
Markdown
문서 작성을 하는 방법은 여러 가지가 있다.
그중 Markdown 문법이 있다.
Markdown 문법은 정말 간단하다.
티스토리 편집기가 HTML과 Markdown 두 가지 모드를 지원할 만큼 대중적이고 간단하다.
하지만 문법이 간단한 만큼 제공되는 기능도 간단하다.
GitHub의 경우 프로젝트에 README.md 파일을 만들도록 가이드하는데 이 파일에 쓰이는 문법이 Markdown 문법이다.
https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes
About READMEs - GitHub Help
About READMEs You can add a README file to your repository to tell other people why your project is useful, what they can do with your project, and how they can use it. A README file, along with a repository license, contribution guidelines, and a code of
help.github.com
README.md가 있으면 프로젝트 페이지의 메인 화면에 표시되어 해당 프로젝트에 대한 설명을 보여준다.
https://github.com/spring-projects/spring-framework
Asciidoc
AsciiDoc은 Markdown을 좀 더 확장하여 사용할 수 있는 형태이다.
또한 AsciiDoc으로 작성된 문서는 HTML, PDF, EPUB, man page 등 다양한 포맷으로 변환할 수 있다.
Markdown과 AsciiDoc은 문법이 거의 유사하다.
어떤 차이가 있는지는 아래 링크에서 확인할 수 있다.
https://asciidoctor.org/docs/asciidoc-vs-markdown/
AsciiDoc vs Markdown
AsciiDoc presents a more sound alternative. The AsciiDoc syntax is more concise than (or at least as concise as) Markdown. At the same time, AsciiDoc offers power and flexibility without requiring the use of HTML or “flavors” for essential syntax such
asciidoctor.org
AsciiDoctor
AsciiDoctor는 AsciiDoc를 HTML5, DocBook, PDF 및 다른 포맷으로 변환하기 위한 루비 기반의 오픈소스이다.
AsciiDoc을 사용하기 위해 제공되는 AsciiDoctor이지만 AsciiDoc 문법을 편하기 쓰기 위해 AsciiDoctor에서 제공하는 추가적인 차이점을 포함하고 있다.
https://asciidoctor.org/docs/asciidoc-asciidoctor-diffs/
Differences between Asciidoctor and AsciiDoc | Asciidoctor
Asciidoctor aims to be compliant with the AsciiDoc syntax, but there are some differences to keep in mind. Many of these differences exist so that Asciidoctor can: enforce rules we believe are too lax or ambiguous in AsciiDoc process documents faster and s
asciidoctor.org
Spring Reference 문서가 어떻게 만들어지는지 설명하기 위해 Markdown -> Asciidoc -> AsciiDoctor까지 설명이 이어졌는데 Spring Reference 문서는 바로 이 AsciiDoctor를 기반으로 만들어졌다.
AsciiDoc이 개발 문서에서 가지는 강점은 바로 include라고 생각한다.
java, properties, html 등 여러 형태로 작성된 개발 소스가 AsciiDoc 문서 내에 include 문법으로 명시되어 있으면 이를 참조한 상태로 문서를 생성하게 된다.
따라서 Spring이 계속 버전업이 되고 기능이 변경되는 경우에 관련된 AsciiDoctor 문서의 갱신이 편리하다.
자바 프로젝트의 경우 AsciiDoctor의 Maven이나 Gradle plugin이 제공된다.
https://asciidoctor.org/docs/asciidoctor-maven-plugin/
Asciidoctor Maven Plugin | Asciidoctor
Developer setup for hacking on this project isn’t very difficult. The requirements are very small: Everything else will be brought in by Maven. This is a typical Maven Java project, nothing special. You should be able to use IntelliJ, Eclipse, or Netbean
asciidoctor.org
해당 가이드대로 프로젝트에 플러그인을 설정하면 해당 플러그인 설정에 지정된 AsciiDoc 문서 폴더에 .adoc 문서를 만들고 빌드하면 해당 문서가 지정된 포맷의 형태로 생성되게 된다.
플러그인의 AsciiDoc 문서 기본 위치는 /src/main/asciidoc/ 이고 생성된 결과물의 기본 위치는 /target/generated-docs/ 이다.
여기까지의 설명을 보고 차근차근 따라 해 봤다면 AsciiDoctor 홈페이지와 동일한 디자인의 문서가 생성되는 것을 확인할 수 있을 것이다.
Spring Doc Resources
Spring Doc Resources는 AsciiDoctor로 생성된 문서의 디자인을 Spring Reference Doc 문서의 디자인 형태로 변환해준다.
해당 프로젝트 페이지의 README.md 내용을 따라서 설정하면 아래와 같은 순서로 문서가 생성된다.
- maven-dependency-plugin이 spring-doc-resources zip 파일을 /refdocs/ 폴더로 압축을 푼다.
- maven-resources-plugin이 /src/main/asciidoc의 문서를 /refdocs/ 폴더로 복사한다. (1의 내용과 같이 합쳐짐)
- asciidoctor-maven-plugin의 문서 기본 위치를 /refdoc/로 설정하여 해당 폴더의 내용을 지정된 포맷의 형태로 생성하게 한다.
spring-doc-resources.zip 파일에는 Spring Reference Doc 스타일에 대한 CSS와 문서의 TOC를 펼치고 접는 기능을 선언한 js, 이 js를 공통으로 참조하기 위한 docinfo-footer.html 파일이 들어있다.
Spring Doc Resources를 사용하려면 아래 repository 설정이 추가되어야 한다. (maven central repository에 없다.)
<repositories>
<repository>
<id>spring-releases</id>
<url>https://repo.spring.io/release</url>
</repository>
</repositories>
'Study > Java' 카테고리의 다른 글
| spring-asciidoctor-extensions 사용해 보기 (0) | 2020.07.17 |
|---|---|
| Spring Framework 5.2.0.RELEASE 이후 Documentation에 Kotlin example이 추가되다. (0) | 2020.07.15 |
| Spring Boot가 2.3.x 이후 build tool을 Gradle로 바꾸다. (0) | 2020.07.14 |
| Spring Boot Dynamic Bean 등록 (0) | 2020.06.25 |
| Spring Rest Docs response body 한글 깨짐 문제 (mockmvc 설정 문제) (0) | 2020.06.19 |
| [troubleshooting] 아직 명확한 해결법을 찾지 못한 Spring Boot web No ServletContext set 에러 현상 (0) | 2020.06.05 |
| Spring Boot 2.3 Release Notes (0) | 2020.05.26 |
| JDK 14 New Features (0) | 2020.03.30 |
| Spring Custom HandlerExceptionResolver 사용하기 (0) | 2020.02.18 |
| 재미로 보는 Spring Project release train naming (0) | 2020.02.07 |
