How to build the documentation

This page describes how to build and contribute to the documentation. It also provides a brief overview of the documentation authoring and generation toolchain.

You will need to be able to build from source.

The process for patching the documentation is the same as any other patch. See How to contribute a patch to gradle.

User Guide

• From the top level souorce directory: ./gradlew userguide.
  • This builds HTML, single page HTML, and PDF versions of the userguide into GRADLESRC/subprojects/gradle-docs/build/docs.
• You can also use the userguideHtml, userguideSingleHtml and userguidePdf tasks to build the different versions individually.

API Documentation and DSL Reference

• From the top level source directory: ./gradlew javadoc groovydoc dslHtml
  • This builds the API documentation into GRADLESRC/subprojects/gradle-docs/build/docs
• You can use these tasks individually, too.

Web Site

• The web site project is located in GRADLESRC/website
• From the GRADLESRC/website directory: ../gradlew -u html
  • This builds the website into GRADLESRC/website/build/website

Other Documentation

• From the top level directory: ./gradlew distDocs
  • This builds the misc. documentation included in the distribution.

Documentation Overview

The userguide is authored using docbook. You can find the source in subprojects/gradle-docs/src/userguide. Some of this content is reused on the website and in the distribution documentation.

The build uses the docbook stylesheets with some customisations in subprojects/gradle-docs/src/stylesheets to generate HTML. It uses Flying Saucer + iText to generate the PDF from the HTML.

The API documentation is authored using javadoc and groovydoc.

The website is authored using HTML.

You should note that the userguide source contains some custom markup:

<apilink>

This is an inline element which adds a link to the API documentation for a particular class or method.

The link will point to the DSL reference for the specified class, if available. Otherwise, it will point to the javadoc or groovydoc for the class as appropriate.

<sample>

This is a block element which adds some source code from one of the sample builds in src/samples.

You can include zero or more <sourcefile> elements, zero or more <output> elements, and optionally one <layout> element. They can appear in any order, and are included in the userguide in the order they appear in the source document.

Attribute includeLocation is optional and defaults to false. When set to true, a tip is included in the userguide to inform the reader when they can find the source for the sample.

<layout>

The <layout> element generates a directory tree listing showing the given files and directories. It will be compared against the actual sample directory layout, to test that the listing included in the userguide matches that in the source. The after attribute is optional. When present, Gradle will be run with the given arguments before checking that the files and directories exist. This way, you can document generated files. The <layout> element should contain a list of file or directory paths, one per line, relative to the sample directory. Directory names must end with a trailing / character.

<sourcefile>

The <sourcefile> element includes a source file in the userguide. It must have a file attribute. This is the path to the file to include, relative to the sample base directory. It may optionally have a snippet attribute, which is the name of the snippet to include from the source file.

<output>

The <output> element includes a screen listing showing the command to be executed and the expected output.

<test>

The <test> elements defines an integration test to exercise the sample. Nothing is included in the userguide for this element.

When you use the <sample> element, a test is added to the integration testsuite to ensure that the sample actually works. If no <output>, <test>, or <layout after='...'> element is present, the test will run gradle tasks in the sample directory, and check that the build does not fail. For each <output> element, the test will run gradle $args and compare the output against the corresponding expected output file in src/samples/userguideOutput. For each <test args='...'> or <layout after='...'> element, the test will run gradle $args.

condition="standalone"

This attribute can be attached to any docbook element to conditionally includes the element in the generated document when the target document is a standalone document, rather than part of the userguide.

<ulink url="website:somepage.html"/>

Adds a link to the given page on the Gradle web site. This will be replaced by a relative link when the content is included in the web site, and an absolute link when the content is included in a stand alone user guide.

Snippets

The sample source files can contain snippets which can be included in the documentation, in place of the entire source file.