Gradle Documentation Plugins

Note	All Gradle documentation content from this repository has been moved to the Gradle User Manual.

This is a collection of very opinionated plugins that support the authoring of documentations for Gradle.

• org.gradle.guides: The single guide project plugin.

• org.gradle.samples: The samples plugin.

• org.gradle.documentation: Used to generate all type of documentation (currently only guides and samples).

How do I use the plugins?

Each of the plugins generates a guide from Asciidoc source.

Guide

• The source for the guide is located in content/index.adoc

• Run ./gradlew guidesMultiPage to generate the guide into build/working/guides/render-guides/<name-of-guide>/index.html.

• Run ./gradlew view<NameOfGuide>Guide to generate the guide and open it in the browser.

• Run ./gradlew check to execute all guide check.

Changelog

0.23.3

• Fix compatibility with Gradle 9.0 (File Permission API)

0.23.2

• Remove deprecated GUtil

0.23.1

• Make all private @TaskAction methods public

0.23

• Upgrade to the Asciidoctor plugin 4.0.1

• Fix compatibility with Gradle 8.0

0.22

• Remove unnecessary dependencies

0.21

• Use tasks as the sanity check task instead of help

0.19.1

• Use docs-asciidoctor-extension 0.11.0

0.19.0

• Use exemplar 1.0.0

• Force upgrade of asciidoctor-groovy-dsl to version 2.0.2 which can be resolved via Maven Central

0.18.0

• Make compatible with Asciidoctor Gradle Plugin 3.x and AsciidoctorJ 2.x

• Use exemplar 0.10.0

0.17.0

• Allow duplicate entries for zipped samples

0.16.9

• Update to support Gradle 7

• Fix resources being included several times

0.16.6

• Use Worker API for some sample related tasks so more things can run in parallel

• Introduce new type of sample binary that does not have an associated zip

0.16.5

• Skip asciidoctor-related validation tasks for non-promoted samples.

• Include a common directory for samples by convention

0.16.4

• Samples can be excluded from the samples index by setting the sample property to false.

• Samples can overwrite generated sanity checks with explicit Exemplar tests

• Exemplar tests located in the tests-groovy and tests-kotlin subdirectory are only executed for the target dsl variant.

0.16.3

• Add samplesInformation to list information about samples and template

• Fix kebab-case handling for template names

0.16.2

• Avoid creating temporary directories during configuration phase

0.16.1

• Normalize the trailing new lines from Gradle output

0.16.0

• Refactoring of the internal of all plugins to share most of the implementation

• Discontinue the Getting Started, Topical and Tutorial plugins in favor of a category property on each guides

• Introduce the org.gradle.guide plugin opinionated to a single guide for the project (replacement for the discontinued plugins)

• Introduce the org.gradle.documentation plugin for building all type of documentation

• Introduce the Asciidoctor content testing for guides and samples

• Remove usage of the org.ysb33r.cloudci and org.ysb33r.gradlerunner plugins

• Improve clarity around the public and internal APIs

0.15.28

• Add checkSamples to run sample checks

• Disable checkstyle on generated tests

0.15.27

• Major changes in samples plugin DSL

0.15.26

• Honor Gradle wrapper execution flag on *nix system

0.15.25

• Honor disabled Exemplar tests from previous test runs

• Order sample index according to sample creation order inside build script

• Capitalize the sample archive base name

• Allow configuration of the sample permalink

• Update Asciidoctor Gradle plugin to version 1.5.9.2

0.15.24

• Allow Asciidoctor tasks to be cacheable

0.15.23

• Avoid filtering any binary files in sample zips

0.15.22

• Fix exemplar testing with generated content

0.15.21

• Fix corrupted wrapper JAR in sample zips

0.15.20

• Fix ClassNotFoundException with org.gradle.samples plugin

0.15.19

• Allow sample display name to be customized (sample.displayName)

• Pass sample display name to Asciidoctor generator as sample-displayName

• Pass sample description to Asciidoctor generator as sample-description

0.15.18

• Use Exemplar 0.9.0

• Allow README Asciidoctor files to use sample extension

• Remove Sample prefix to on the auto-generated sample index page

• Remove .gradle and build directory from sample archives

• Remove Asciidoctor tags from Gradle script files inside archives

0.15.17

• Fix Exemplar tests for multiple samples

0.15.16

• Introduce sample description on the model

• Expose Asciidoctor task on the sample model

• Disable checkstyle check on the Exemplar generated source

• Automatically add the license file if available to all sample archives

0.15.15

• Allow samples archive content to be customized

• Allow samples archive content to be generated

• Allow samples to be tested via Exemplar

0.15.14

• Introduce the Gradle samples plugin.

0.15.13

• Fix link to C++ guides.

0.15.12

• Use https in LICENSE file.

0.15.11

• Add GitHub repository configuration task to setupGuide.

0.15.10

• Add conventions for the guide DSL:

  • repositoryPath defaults to gradle-guides/${project.name}

  • title defaults to title case of the project.name

  • description defaults to title

0.15.9

• Fix repoPath forwarding to repositoryPath property.

• Remove usage of mainAuthor in preparation to removing the property.

0.15.8

• Introduced repositoryPath property on the guide DSL to replace repoPath getter/setter.

• Deprecate repoPath getter/setter.

• Add setup tasks to generate common files:

  • .github/CODE_OF_CONDUCT.md generated by GenerateCodeOfConductFile

  • .github/dco.yml generated by GenerateDeveloperCertificateOfOriginConfiguration

  • .gitignore generated by GenerateGitIgnoreConfiguration

  • .editorconfig generated by GenerateEditorConfiguration

  • LICENSE generated by GenerateLicenseFile

  • README.adoc generated by GenerateReadeMeFile

• Add setupGuide lifecycle task to configure everything about a guide by generating the common files above and configure the GitHub repository description and homepage.

0.15.7

• Model the minimum Gradle version of a guide by introducing minimumGradleVersion property on the guide DSL.

0.15.6

• More reliable viewGuide implementation.

• The standard assemble task also generates the guide output.

Plugins development

Releasing the plugins

1. Edit build.gradle.kts and replace -SNAPSHOT version with the version to release.

2. Edit this README to update the changes section.

3. Commit and create tag, e.g. git tag v0.15.9.

4. Push changes and tag to master, e.g. git push && git push origin v0.15.9

5. Run the Publish Documentation Plugins build on TeamCity.

6. Create GitHub release.

7. Edit build.gradle.kts and replace version with -SNAPSHOT for next version.