swagger를 이용한 문서화 중 asciidoctor-maven-plugin 사용법

AsciiDoc을 html이나 pdf로 변경할 때 asciidoctor-maven-plugin 또는 asciidoctor-gradle-plugin을 사용한다.

설치

<plugins>
    <plugin>
        <groupId>org.asciidoctor</groupId>
        <artifactId>asciidoctor-maven-plugin</artifactId>
        <version>1.5.2</version>
        ...
    </plugin>
</plugins>

사용법

<plugin>
    ...
    <executions>
        <execution>
            <id>output-html</id>              (1)
            <phase>generate-resources</phase> (2)
            <goals>
                <goal>process-asciidoc</goal> (3)
            </goals>
        </execution>
    </executions>
</plugin>

1. unique id 셋팅

2. 단계 명시

3. asciidoctor maven plugin goal

설정(configuration options)

sourceDirectory

defaults to ${basedir}/src/main/asciidoc

sourceDocumentName

an override to process a single source file; defaults to all files in ${sourceDirectory}

sourceDocumentExtensions

(named extensions in v1.5.3 and below) a List<String> of non-standard file extensions to render. Currently ad, adoc, and asciidoc will be rendered by default

outputDirectory

defaults to ${project.build.directory}/generated-docs

baseDir

(not Maven’s basedir) enables to set the root path for resouces (e.g. included files), defaults to ${sourceDirectory}

skip

set this to true to bypass generation, defaults to false

preserveDirectories

enables to specify whether the documents should be rendered in the same folder structure as in the source directory or not, defaults to false. When true, instead of generating all output in a single folder, output files are generated in the same structure. See the following example

    ├── docs                          ├── docs
    │   ├── examples.adoc             │   ├── examples.html
    │   └── examples            =>    │   └── examples
    │       ├── html.adoc             │       ├── html.html
    │       └── docbook.adoc          │       └── docbook.html
    └── index.adoc                    └── index.html

relativeBaseDir

only used when baseDir is not set, enables to specify that each AsciiDoc file must search for its resources in the same folder (for example, included files). Internally, for each AsciiDoc source, sets baseDir to the same path as the source file. Defaults to false

imagesDir

defaults to images, which will be relative to the directory containing the source files

backend

defaults to docbook

doctype

defaults to null (which trigger’s Asciidoctor’s default of article)

eruby

defaults to erb, the version used in JRuby

headerFooter

defaults to true

templateDir

disabled by default, defaults to null

templateEngine

disabled by default

sourceHighlighter

enables and sets the source highlighter (currently coderay or highlightjs are supported)

attributes

a Map<String,Object> of attributes to pass to Asciidoctor, defaults to null

embedAssets

Embedd the CSS file, etc into the output, defaults to false

gemPaths

enables to specify the location to one or more gem installation directories (same as GEM_PATH environment var),empty by default

requires

a List<String> to specify additional Ruby libraries not packaged in AsciidoctorJ, empty by default

extensions

List of extensions to include during the conversion process (see AsciidoctorJ’s Extension API for information about the available options). For each extension, the implementation class must be specified in the className parameter, theblockName is only required when configuring a BlockProcessor, BlockMacroProcessor or InlineMacroProcessor. Here follows a configuration example:

<plugin>
    ...
    <executions>
        <execution>
            <configuration>
                ...
                <extensions>
                    <extension>
                        <className>org.asciidoctor.maven.SomePreprocessor</className>
                    </extension>
                    <extension>
                        <className>org.asciidoctor.maven.SomeBlockProcessor</className>
                        <blockName>yell</blockName>
                    </extension>
                </extensions>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency> (1)
            <groupId>org.asciidoctor.maven</groupId>
            <artifactId>my-asciidoctor-extensions</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</plugin>

1. Note that processors must be included in the plugin’s execution classpath, not in the project’s

팁

1. 목차 좌, 우(left, right) 설정

<configuration>
    ...
    <attributes>
        ...
        <toc>right</toc>
        ...
    </attributes>
    ...
</configuration>

2. 목록 번호 매김

<configuration>
    ...
    <attributes>
        ...
        <numbered>true</numbered>
        ...
    </attributes>
    ...
</configuration>

참고

https://github.com/asciidoctor/asciidoctor-maven-plugin