spring-attic / docbook-reference-plugin

PdfDocbookReferenceTask

This repository is no longer actively maintained by VMware, Inc.

DocBook Plugin for Gradle

Small plugin used internally by the Spring Team to create documentation from docbook sources.

Configuration

See tags to determine the latest available version. Then configure the plugin in your project as follows, using spring-framework/build.gradle as an example:

buildscript {
    repositories {
        maven { url 'http://repo.spring.io/plugins-release' }
    }
    dependencies {
        classpath 'io.spring.gradle:docbook-reference-plugin:0.3.0'
    }
}

// ...

configure(rootproject) {
    apply plugin: 'docbook-reference'

    reference {
        sourceDir = file('src/reference/docbook')
        pdfFilename = 'spring-framework-reference.pdf'

        // optionally

        // configure fop for pdf generation
        fopUserConfig = file('src/reference/fop/fop-userconfig.xml')

        // Configure which files have ${} expanded
        expandPlaceholders = '**/index.xml, **/other.xml'
        
        // Delete the index.fo after creating PDF
        retainFo = false
    }

    task docsZip(type: Zip) {
        group = 'Distribution'
        baseName = 'spring-framework'
        classifier = 'docs'

        // ...

        from (reference) {
            into 'reference'
        }
    }

    // ...

    artifacts {
        archives docsZip
    }
}

See contents of the spring-framework/src/reference/docbook for details.

Usage

$ gradle referenceHtmlMulti
$ gradle referenceHtmlSingle
$ gradle referencePdf
$ gradle referenceEpub
$ gradle reference  # all of the above
$ gradle build      # depends on `reference` because of "artifacts" arrangement

Output

$ open build/reference/html/index.html
$ open build/reference/htmlsingle/index.html
$ open build/reference/pdf/spring-framework-reference.pdf
$ open build/reference/epub/spring-framework-reference.epub

Maintenance

See How to release the docbook reference plugin wiki page.

docbook-reference-plugin's Issues

Wrong xslthl-config.xml used

I'm not able to get code highlighting work with groovy and yaml. This seems to be caused by task using a wrong xslthl-config.xml file.

Executing task ':referenceHtmlSingle' (up-to-date check took 0.003 secs) due to:
  Output file /home/jvalkealahti/repos/jvalkeal/spring-hadoop-docs/build/reference has changed.
  Output file /home/jvalkealahti/repos/jvalkeal/spring-hadoop-docs/build/reference/htmlsingle/images/callouts/4.gif has been removed.
  Output file /home/jvalkealahti/repos/jvalkeal/spring-hadoop-docs/build/reference/htmlsingle/images/up.png has been removed.
Note: namesp. cut : stripped namespace before processing           Spring for Apache Hadoop - Reference Documentation
Note: namesp. cut : processing stripped document                   Spring for Apache Hadoop - Reference Documentation
Loading Xslthl configuration from file:/home/jvalkealahti/repos/jvalkeal/spring-hadoop-docs/build/docbook-resources/highlighting/xslthl-config.xml...
:referenceHtmlSingle (Thread[main,5,main]) completed. Took 4.392 secs.

I believe it should load /home/jvalkealahti/repos/jvalkeal/spring-hadoop-docs/build/docbook-resources/xsl/xslthl-config.xml instead.

Boot is using maven plugins and defines these files manually which is not an option, afaik, for gradle. Also it looks like framework core docs also doesn't highlight groovy sources (i.e. Groovy Bean Definition DSL section).

MissingPropertyException: No such property: level for class: OutputEventListenerBackedLogger

When running with Gradle 2.4 pdf rendering fails with the following:

Caused by: groovy.lang.MissingPropertyException: No such property: level for class: org.gradle.logging.internal.slf4j.OutputEventListenerBackedLogger
    at PdfDocbookReferenceTask.postTransform(DocbookReferencePlugin.groovy:400)
    at AbstractDocbookReferenceTask.transform(DocbookReferencePlugin.groovy:155)
    at org.gradle.internal.reflect.JavaMethod.invoke(JavaMethod.java:75)
    at org.gradle.api.internal.project.taskfactory.AnnotationProcessingTaskFactory$StandardTaskAction.doExecute(AnnotationProcessingTaskFactory.java:226)
    at org.gradle.api.internal.project.taskfactory.AnnotationProcessingTaskFactory$StandardTaskAction.execute(AnnotationProcessingTaskFactory.java:219)
    at org.gradle.api.internal.project.taskfactory.AnnotationProcessingTaskFactory$StandardTaskAction.execute(AnnotationProcessingTaskFactory.java:208)
    at org.gradle.api.internal.AbstractTask$TaskActionWrapper.execute(AbstractTask.java:589)
    at org.gradle.api.internal.AbstractTask$TaskActionWrapper.execute(AbstractTask.java:572)
    at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter.executeAction(ExecuteActionsTaskExecuter.java:80)
    at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter.executeActions(ExecuteActionsTaskExecuter.java:61)
    ... 47 more

The plugin was using an implementation specific property and Gradle has changed the underlying implementation. Ultimately, this block of code is not necessary since the logger will inherit from the parent anyways.