swagger2markup/swagger2markup-builder/README.adoc

= MarkupDocBuilder
:author: Robert Winkler
:version: 1.1.1
:hardbreaks:

== Overview

This project is a Markup document builder (AsciiDoc, Markdown and ConfluenceWiki). The primary goal of this project is to simplify the creation of Markup documents. The builder is used by https://github.com/RobWin/swagger2markup[swagger2markup].

The project requires at least JDK 7.

=== Usage
=== Adding MarkupDocBuilder to your project
The project is published in JCenter and Maven Central.

==== Maven

[source,xml, subs="specialcharacters,attributes"]
----
<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>central</id>
        <name>bintray</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>markup-document-builder</artifactId>
    <version>{version}</version>
</dependency>
----

==== Gradle

[source,groovy, subs="attributes"]
----
repositories {
    jcenter()
}

compile "io.github.swagger2markup:markup-document-builder:{version}"
----

=== Using MarkupDocBuilder

The MarkupDocBuilder allows to build an AsciiDoc or Markdown document via the Builder pattern.

[source,java]
----
public class MarkupDocBuilderTest {

    List<String> tableRowsInPSV;

    @Before
    public void setUp(){
        tableRowsInPSV = new ArrayList<>();
        tableRowsInPSV.add("Header 1 | Header 2 | Header2");
        tableRowsInPSV.add("Row 1, Column 1 | Row 1, Column 2 | Row 1, Column 3");
        tableRowsInPSV.add("Row 2, Column 1 | Row 2, Column 2 | Row 2, Column 3");
    }


    @Test
    public void testToAsciiDocFile() throws IOException {
        MarkupDocBuilder builder = MarkupDocBuilders.documentBuilder(MarkupLanguage.ASCIIDOC);
        builder.documentTitle("Test title")
                .sectionTitleLevel1("Section Level 1a")
                .sectionTitleLevel2("Section Level 2a")
                .sectionTitleLevel3("Section Level 3a")
                .paragraph("Paragraph with long text bla bla bla bla bla")
                .listing("Source code listing")
                .source("MarkupDocBuilder builder = MarkupDocBuilders.documentBuilder(MarkupLanguage.ASCIIDOC)", "java")
                .tableWithHeaderRow(tableRowsInPSV)
                .sectionTitleLevel1("Section Level 1b")
                .sectionTitleLevel2("Section Level 2b")
                .boldTextLine("Bold text line b")
                .italicTextLine("Italic text line b")
                .unorderedList(Arrays.asList("Entry1", "Entry2", "Entry 2"))
                .writeToFile("build/tmp", "test", StandardCharsets.UTF_8);
    }

    @Test
     public void testToMarkdownDocFile() throws IOException {
        MarkupDocBuilder builder = MarkupDocBuilders.documentBuilder(MarkupLanguage.MARKDOWN);
        builder.documentTitle("Test title")
                .sectionTitleLevel1("Section Level 1a")
                .sectionTitleLevel2("Section Level 2a")
                .sectionTitleLevel3("Section Level 3a")
                .paragraph("Paragraph with long text bla bla bla bla bla")
                .listing("Source code listing")
                .source("MarkupDocBuilder builder = MarkupDocBuilders.documentBuilder(MarkupLanguage.MARKDOWN)", "java")
                .tableWithHeaderRow(tableRowsInPSV)
                .sectionTitleLevel1("Section Level 1b")
                .sectionTitleLevel2("Section Level 2b")
                .boldTextLine("Bold text line b")
                .italicTextLine("Italic text line b")
                .unorderedList(Arrays.asList("Entry1", "Entry2", "Entry 2"))
                .writeToFile("build/tmp", "test", StandardCharsets.UTF_8);
    }

}
----

=== Generated HTML using AsciidoctorJ
You can generate your PDF or HTML documentation via https://github.com/asciidoctor/asciidoctorj[asciidoctorj] or even better via the https://github.com/asciidoctor/asciidoctor-gradle-plugin[asciidoctor-gradle-plugin] or https://github.com/aalmiray/markdown-gradle-plugin[markdown-gradle-plugin].

image::images/asciidoc_html.jpg[asciidoc_html]

== License

Copyright {docyear} Robert Winkler

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.