AsciidoctorJ LogHandler to collect log entries into a single file.

URLs

Do you want to improve this page? Please edit it on GitHub.

Description

When AsciidoctorJ converts a document, it writes issues to the console (malformed AsciiDoc constructs, missing attribute, errors…). This extension collect those issues and to write them into a single log file: build/asciidoctor.log. This file can be then used by other tools. For example the Jenkins Warnings Next Generation Plugin, can collect the asciidoctor issues in order to display them as part of the job result.

AsciidoctorJ version

The latest version of this extension is built and tested with version 2.0.0 of org.asciidoctor:asciidoctorj.

Usage

The extension is published on maven central and can be directly consumed from a gradle build.

Integration in a gradle build

The fr.jmini.asciidoctorj:file-logger jar can be declared as dependency of the asciidoctor task:

Listing 1. Configuration of the asciidoctor task in a gradle build
asciidoctor {
    sourceDir = file('docs')
    outputDir = file('build/generated-docs')
    attributes = ['project-version'      : "$version",
                  'attribute-missing'    : 'warn', (2)
                  'toc'                  : 'left',
                  'icons'                : 'font',
                  'sectanchors'          : 'true',
                  'idprefix'             : '',
                  'idseparator'          : '-']
    repositories {
        mavenCentral()
    }
    dependencies {
        asciidoctor 'fr.jmini.asciidoctorj:file-logger:1.0.0' (1)
    }
}
1 Dependency declaration
2 This kind of setting is important to force asciidoctor to produce more logs

For a complete example, see: build.gradle

Output example

The content of the build/asciidoc.adoc example can look like this:

Listing 2. Example content for the log file
# AsciidoctorJ file-logger - 2019-09-04T11:10:32.126Z #
{"fileName":"/tmp/file.adoc","lineStart":5,"message":"include file not found: /tmp/other.adoc","category":"Asciidoctor","severity":"ERROR"}
{"fileName":"/tmp/file.adoc","lineStart":7,"message":"list item index: expected 1, got 8","category":"Asciidoctor","severity":"HIGH"}
{"message":"skipping reference to missing attribute: bla","category":"Asciidoctor","severity":"HIGH"}

Integration with Jenkins

You need to install the Warnings Next Generation Plugin (tested with version 5.3.0).

In your build configuration, in the "Post-build Actions" section, add a "Record compiler warnings and static analysis results" item:

Record compiler warnings and static analysis results configuration

Configure the item with following values:

  • Tool: Warnings Plugin Native Format

    • Report File Pattern: build/asciidoctor.log

    • Custom ID: asciidoctor (optional)

    • Custom Name: Asciidoctor Logs (optional)

Here the same configuration as Jenkins pipeline script:

Listing 3. Jenkins pipeline configuration
recordIssues(tools: [issues(id: 'asciidoctor', name: 'Asciidoctor Logs', pattern: 'build/asciidoctor.log')])

Source Code

As for any grade plugin, the source code of the plugin is available in the src/ folder.

Build

This project is using gradle.

Command to build the sources locally:

./gradlew build

Command to deploy to your local maven repository:

./gradlew publishToMavenLocal

Command to build the documentation page:

./gradlew asciidoctor

The output of this command is an HTML page located at <git repo root>/build/docs/html5/index.html.

For project maintainers

signing.gnupg.keyName and signing.gnupg.passphrase are expected to be set in your local gradle.properties file to be able to sign. sonatypeUser and sonatypePassword are expected to be set in order to be able to publish to a distant repository.

Command to build and publish the result to maven central:

./gradlew publishToNexus

Command to upload the documentation page on GitHub pages:

./gradlew gitPublishPush

Command to perform a release:

./gradlew release -Prelease.useAutomaticVersion=true

Using ssh-agent

Some tasks requires pushing into the distant git repository (release task or updating the gh-pages branch). If they are failing with errors like this:

org.eclipse.jgit.api.errors.TransportException: ... Permission denied (publickey).

Then ssh-agent can be used.

eval `ssh-agent -s`
ssh-add ~/.ssh/id_rsa

(source for this approach)

Get in touch

Use the AsciidoctorJ file-logger issue tracker on GitHub.

You can also contact me on Twitter: @j2r2b

License

Eclipse Public License - v 2.0