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/build/distributions/exploded/docs.
- You can also use the userguideHtml, userguideSingleHtml and userguidePdf tasks to build the different versions individually.
API Documentation
- From the top level source directory: ./gradlew javadoc groovydoc
- This builds the API documentation into GRADLESRC/build/distributions/exploded/docs
Web Site
- The web site project is located in GRADLESRC/website
- From the GRADLESRC/website directory: ../gradlew 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 src/docs/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 src/docs/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.
You can use the <apilink classname='org.gradle.api.Project'> interface to do stuff. Here is a link to a groovy class: <apilink classname='org.gradle.api.task.bundling.Tar' lang='groovy'/>
When you use the <apilink> element, a check is added to the integration test suite to ensure that the link points to a documented class.
<sample>
This is a block element which adds some source code from one of the sample builds in src/samples.
<sample id='aUniqueIdForTheSample' dir='userguide/someSample' includeLocation="true" title='a title for the sample'> <layout> dir1 dir1/build.gradle dir2 dir2/src/main/java/org/gradle/SomeClass.java </layout> <sourcefile file='build.gradle'/> <sourcefile file='water/build.gradle'/> <output args='-PsomeProp=1020 hello'/> <output args='-q hello' outputfile='someSample.out'/> <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.
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.
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 <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.
The <output> element includes a screen listing showing the command to be executed and the expected output.
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> or <test> element is present, the test will run gradle -t 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> element, the test will run gradle $args.
<standalonedocument>
This is a block element which conditionally includes some content in the generated document when the target document is a standalone document, rather than part of the userguide.
<standalonedocument> <para>You are not reading the user guide right now.</para> </standalonedocument>
