Java, Web and Mobile

Blog

Automatically publish documentation using GitLab

|
Continuous Integration

This guide walks you through the process setting up your configuration for generation and publishing html-documentation automatically. Since it is part of a series of guides about GitLab-CI we assume that the reader is already familiar with the basics. Otherwise, we recommend to first go to our getting started guide and work the way back to this guide.

What you will achieve

A maven build which generates a html-documentation. This documentation is published for each merge on the master branch within GitLab.

What you will need

  • An account on a GitLab-Server (for example gitlab.com)
  • A sample program with initial configuration
  • Basic knowledge about the GitLab-CI
  • Git in Version 2.0.0 or later
  • Jdk 1.8
  • Maven 3.0+

Set up

You can use any maven project in combination with the following GitLab-CI configuration or a similar one. If you have none on hand, you can create one with spring initializer or use this sample program.

The following configuration defines two jobs. The first compiles the app and run the test except for tagged commits. The other one is run on tagged commits. In this case, the app is compiled, tested and deployed. Finally, the second one allows to download the created jar.

Automatically generated and published documentation

AsciiDoc is the chosen tool for documentation, which is human-readable and plain text. Therefore, it can easily be integrated to the git repository. The major advantage of AsciiDoc is the ability to generate different output formats like PDF or HTML. The latter is used for publishing our documentation.

In order to generate the HTML output Maven plugin asciidoctor is utilized. An example configuration file can be found below.

The HTML output is provided in target/generated-docs/. As a further step, the HTML version is published under http://projectGroup.gitlab-server.tld/projectName. For this GitLab Pages will be utilized. In line with best knowledge of the author, there is no way to publishing more than one page simultaneously. Therefore publishing the documentation only in one branch is recommended. For a deep dive, we refer to the GitLab documentation.

In order to publish another job pages is added which creates the necessary directory public and keeps the results. Notice that all files and directories that are not marked as artifacts are cleaned up after the jobs are finished.

Conclusion

We have seen how to enable GitLab to provide us with an up-to-date auto generated documentation of our releases.