The following is some help for working with the docs, all file paths are relative to this directory unless specified otherwise.
The release notes are generated from
h2 tag and
h3 will be listed in the generated TOC.
h3 all content after the first element (usually a
p) will be collapsed/expandable, up until the next
h4 all content will be collapsed/expandable, up until the next
h3 may include an incubating marker
(i) at the end of its text to indicate that the feature is incubating.
Here's an example:
## h2 New and Noteworthy ### h3 Some feature (i) This is some incubating feature. #### h4 Some detail This detail about the feature is collapsed. The reader can expand it if they are interested.
viewReleaseNotes task to generate the release notes, and open them in your browser (requires Java 6).
You can run the
editReleaseNotes task to open the raw markdown notes in whatever editor is registered for this file type (requires Java 6).
The source for the userguide lives @
src/docs/userguide. The userguide is authored using docbook and uses docbook stylesheets with some customizations in
src/stylesheets to generate HTML. It uses Flying Saucer + iText to generate the PDF from the HTML.
When adding new content, it's generally best to find an example of the kind of content that you want to add somewhere else in the userguide and copy it.
To generate the userguide and see your changes, run:
You can then view the built html in
build/docs/userguide (open the
userguide.html) to view the front page.
Useful docbook tags:
See the docbook reference for a list of all available tags.
Here are some useful ones:
For code snippets
This is an inline element which adds a link to the API documentation for a particular class or method.
You can use the <apilink class='org.gradle.api.Project' /> interface to do stuff. Here is a link to a groovy class: <apilink class='org.gradle.api.task.bundling.Tar' />
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.
To link to a method:
<apilink class='org.gradle.api.Project' method="apply(java.util.Map)" />
This is a block element which adds some source code from one of the sample builds in
<sample id='aUniqueIdForTheSample' dir='userguide/someSample' includeLocation="true" title='a title for the sample'> <layout after='someTask'> dir1/ dir1/build.gradle dir2/ dir2/src/main/java/org/gradle/SomeClass.java </layout> <sourcefile file='build.gradle'/> <sourcefile file='water/build.gradle' snippet='some-snippet'/> <output args='-PsomeProp=1020 hello'/> <output args='-q hello' outputFile='someSample.out' ignoreExtraLines="true" ignoreLineOrder="true" expectFailure="false"/> <test args="-q someTask"/> </sample>
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.
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> 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
<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> element includes a screen listing showing the command to be executed and the expected output.
<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
<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
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.
<section condition="standalone"> <para>You are not reading the user guide right now.</para> </section>
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.
The sample source files can contain snippets which can be included in the documentation, in place of the entire source file.
// START SNIPPET something some code // END SNIPPET something some other code
The reference documentation (i.e. dsl, groovydoc, javadoc etc.) are extracted from the in code doc comments.
To build these, run:
./gradlew docs:dslHtml ./gradlew docs:javadoc ./gradlew docs:groovydoc
The output is available in the
groovydoc directories respectively within
Building all the docs
There is a convenience task to build all of the documentation: