Hello all!
I want to use Asciidoctor to generate my documentation. Therefore I set up a gradle documentation project an in ‘build.gradle’ I am using the Asciidoctor Gradle plugin to translate my documentation to on of these backends:
- HTML (one big file) - HTML (many small files) - PDF (via Docbook) - epub (via Docbook)
Since I can set the asciidoctor-gradle-plugin options only for one backend type I need one ‘build.gradle’ for each backend format. The source (the asciidoctor files) are all the same for each backend.
Can anyone point me to the Gradle documentation or an example on how to do this in Gradle? I want to solve how to setup and link the project structure, not a technically issue with Asciidoctor or Docbook.
Kind regards, Christian
The idiomatic Gradle solution would be to declare one Asciidoctor task per backend. Another option is to conditionally configure the task depending on, say, the value of a system or project property passed on the command line. In terms of build scripts, I’d put all Asciidoctor related code into ‘gradle/asciidoctor.gradle’ and apply it with ‘apply from: “$rootDir/gradle/asciidoctor.gradle”’.
I tried one Asciidoctor task per backend, so I separated common options from specific options. My solution looks like:
asciidoctor {
options = [
logDocuments: true,
attributes: [
imagesdir: ‘./images’,
icons: ‘font’,
experimental: true
]
]
}
task generateHTML (description: ‘Generates single and multiple HTML documentation.’, group: ‘Documentation’) << {
asciidoctor.backend = ‘html5’
asciidoctor.outputDir = new File("$buildDir/asciidoc/html")
asciidoctor.options.attributes.copycss = true
}
task generateDocbook(description: ‘Generates DOCBOOK documentation.’, group: ‘Documentation’) << {
asciidoctor.backend = ‘docbook’
asciidoctor.outputDir = new File("$buildDir/asciidoc/docbook")
}
configure([generateHTML, generateDocbook]) {
finalizedBy asciidoctor
}
Is this the correct approach?
That’s not how you’d declare multiple tasks. Each ‘generate’ task must have a ‘type: …’, rather than configuring ‘asciidoctor’.
Looking at your sample code, i think this is not going to work. As far as i know, the asciidoctor task will only be called once (not twice after generateDocbook and generateHTML), using the latest configuration (e.g. asciidoctor.backend) that has been assigned. To call the plugin multiple times, you can use subprojects (‘docbook’, ‘html5’). The subproject is the container that will host different asciidoctor configurations, and will call the asciidoctor task multiple times. Something along the lines
settings.xml:
include 'docbook'
include 'html5'
build.gradle:
subprojects {
apply plugin: 'asciidoctor'
}
project('docbook') {
asciidoctor.backend = project.name
}
I see, thanks a lot. So I ended up in doing:
import org.asciidoctor.gradle.AsciidoctorTask
// common settings
tasks.withType(AsciidoctorTask) { docTask ->
options = [
logDocuments: true,
attributes: [
imagesdir: ‘./images’,
icons: ‘font’,
experimental: true
]
]
}
task generateHTML (type: AsciidoctorTask, description: ‘Generates single and multiple HTML documentation.’, group: ‘Documentation’) {
backend = ‘html5’
outputDir = new File("$buildDir/asciidoc/html")
options.attributes.copycss = true
}
task generateDocbook (type: AsciidoctorTask, description: ‘Generates DOCBOOK documentation.’, group: ‘Documentation’) {
backend = ‘docbook’
outputDir = new File("$buildDir/asciidoc/docbook")
}
Much clearer,
Sorry, I saw your answer only after I was posting the following answer.