We call document one page of the documentation which corresponds to an HTML page. These documents are converted from the .adoc files.

Generate html

To convert .adoc to .html, we use asciidoctor-maven-plugin plugin. It’s configure in pom.xml and it’s can be run in one phase of the maven lifecycle (generally the package phase).

By default, files started with _ are not converted to HTML by this plugin. We have chosen to start all approved file names with an _. They are only chapters of documents. They need to be included in a file that will be converted into HTML. So, this makes it easier to reuse these chapters and organize the documentation.

To have a file that not start with _, we need to generate one. The HtmlPageExtension extension is made for that. When a test class used this extension, it will generate a simple .adoc file that include the approved file of the same class. The final HTML file will contain all the chapters generated from methods of this class.

Example of class creating the file that will be converted into HTML
@ExtendWith(HtmlPageExtension.class)
public class HtmlTest {
    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

}

Files in folder src/test/docs/com/github/docastest/samples/generateHtml

  • HtmlTest.adoc

  • _HtmlTest.approved.adoc

  • _HtmlTest.test_A.approved.adoc

Content of the file src/test/docs/com/github/docastest/samples/generateHtml/HtmlTest.adoc
include::_HtmlTest.approved.adoc[]

Generate html with nested class

With nested class, only class with direct extension generate a page

Example of class creating the file that will be converted into HTML
@ExtendWith(HtmlPageExtension.class)
public class HtmlNestedTest {
    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

    @Nested
    public class HtmlNestedClassTest {
        @Test
        public void test_in_nested_class() {
            doc.write("In my *test* in nested class");
        }
    }

}

Files in folder src/test/docs/com/github/docastest/samples/generateNestedHtml

  • HtmlNestedTest.adoc

  • _HtmlNestedTest.HtmlNestedClassTest.test_in_nested_class.approved.adoc

  • _HtmlNestedTest.approved.adoc

  • _HtmlNestedTest.test_A.approved.adoc

Generate html only on nested class

It’s not possible to generate a page on a nested class. A nested class do not have is own file for the class. Every methods and classes are included in the approved file for the java file.

Example of class with extension on nested class
public class HtmlOnlyNestedTest {
    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

    @Nested
    @ExtendWith(HtmlPageExtension.class)
    public class HtmlNestedClassTest {
        @Test
        public void test_in_nested_class() {
            doc.write("In my *test* in nested class");
        }
    }

}

Files in folder src/test/docs/com/github/docastest/samples/generateOnlyNestedHtml

  • _HtmlOnlyNestedTest.HtmlNestedClassTest.test_in_nested_class.approved.adoc

  • _HtmlOnlyNestedTest.approved.adoc

  • _HtmlOnlyNestedTest.test_A.approved.adoc

Customize document options

By default, HtmlPageExtension create a file with only one include of the approved class file. This file is the right place to specify some specific information on how displaying the page. We can doing it extending HtmlPageExtension and redefined content to add options we need. Here, we create an inner class but we can use a main class to reuse it in several tests.

Example to add header into file to convert into HTML
@ExtendWith(HtmlHeaderTest.HtmlPageHeaderExtension.class)
public class HtmlHeaderTest {
    static class HtmlPageHeaderExtension extends HtmlPageExtension {
        @Override
        public String content(Class<?> clazz) {
            return String.join("\n",
                    ":toc: left",
                    ":nofooter:",
                    super.content(clazz));
        }
    }

    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

}
Content of the file src/test/docs/com/github/docastest/samples/htmlPageHeader/HtmlHeaderTest.adoc
:toc: left
:nofooter:
include::_HtmlHeaderTest.approved.adoc[]

Define name and path for the output file

By default, HtmlPageExtension create a file with a name coming from the class To change it, we can extending HtmlPageExtension and redefined name method.

Example of class creating a file to convert into HTML
@ExtendWith(HtmlNameTest.HtmlPageHeaderExtension.class)
public class HtmlNameTest {
    static class HtmlPageHeaderExtension extends HtmlPageExtension {
        @Override
        public Path getFilePath(Class<?> clazz) {
            return new DocPath(clazz).page().folder().resolve("index.adoc");
        }
    }

    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

}

Files in folder src/test/docs/com/github/docastest/samples/htmlPageName

  • _HtmlNameTest.approved.adoc

  • _HtmlNameTest.test_A.approved.adoc

  • index.adoc

Define name and path for the output file with constructor

You can create an HtmlPageExtension giving the file name to generate. The name should not contain the extension. It will be added to the given name. The file is placed from the root of the project. It’s an easy way to generate the index file of the project.

Example of class creating a named file to convert into HTML
public class HtmlNameConstructorTest {
    @RegisterExtension
    static final ApprovalsExtension doc = new SimpleApprovalsExtension();

    static Path path = new DocPath(HtmlNameConstructorTest.class).packagePath();
    @RegisterExtension
    static final HtmlPageExtension page = new HtmlPageExtension(path.resolve("index").toString());

    @Test
    public void test_A() {
        doc.write("In my *test*");
    }

}

Files in folder src/test/docs/com/github/docastest/samples/htmlPageConstructor

  • _HtmlNameConstructorTest.approved.adoc

  • _HtmlNameConstructorTest.test_A.approved.adoc

  • index.adoc