Skip to content
A collection of opinionated plugins to support authoring of guides
Groovy Java HTML Kotlin
Branch: master
Clone or download
Latest commit 8cd5e6f Dec 12, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Disable DCO checks for Gradle members May 22, 2019
.teamcity Update credentials for releasing Dec 6, 2019
gradle Update wrapper hash Oct 8, 2019
src Keep execution flag wrapper script Dec 10, 2019
.gitignore Add more excludes Aug 11, 2017
LICENSE.txt
README.adoc Release version 0.15.26 Dec 12, 2019
build.gradle Prepare version 0.15.27 Dec 12, 2019
gradle.properties
gradlew Update Gradle wrapper to 5.4.1 May 8, 2019
gradlew.bat Update Gradle wrapper to 5.4.1 May 8, 2019
settings.gradle.kts Convert settings.gradle to Kotlin DSL Jun 8, 2019

README.adoc

Gradle Guides Plugins Build Status

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

  • org.gradle.guides.base: The base of all of the subsequent plugins.

  • org.gradle.guides.getting-started: Used by all new Getting Started guides.

  • org.gradle.guides.topical: Used by all new Topical guides.

  • org.gradle.guides.tutorial: Used by all new Tutorials.

  • org.gradle.guides.test-jvm-code: Used to test JVM-based code snippets.

How do I use the plugins?

Each of the plugins generates a guide from Asciidoc source. They all share the same conventions:

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

  • Run ./gradlew asciidoctor to generate the guide into build/html5/index.html.

  • Run ./gradlew viewGuide to generate the guide and open it in the browser.

Base plugin

  • Adds guide extension.

  • Adds asciidoctor task with appropriate defaults for guide authoring. This task is also linked into the build lifecycle.

  • Adds asciidoctorAttributes task.

  • Adds publishGhPages task for publishing guide to gh-pages. (Used on Travis).

  • Adds special Travis CI support via the travisci block.

  • Adds checkLinks task to check hyperlinks in generated pages. (In the current release only absolute URLs are supported).

  • Adds gradleRunner task to allow automating one set of steps described in a guide.

  • Adds docs-asciidoctor-extensions library responsible for injecting navigation and CSS/JS

The guide extension

This GuidesExtension always has to be configured for a guide. (The initial repository generation process will probably provide a suitable default).

guide {
    repositoryPath.set("gradle-guides/creating-multi-project-builds") // (1)
}
  1. Set the GitHub URL after github.com.

The asciidoctorAttributes task

This task tells guide authors which Asciidoctor attributes are passed down from Gradle to the asciidoctor task

$ ./gradlew asciidoctorAttributes

:asciidoctorAttributes
Current Asciidoctor Attributes
==============================
source-highlighter: coderay
coderay-linenums-mode: table
imagesdir: images
stylesheet: null
linkcss: true
docinfodir: .
docinfo1:
icons: font
sectanchors: true
sectlinks: true
linkattrs: true
encoding: utf-8
idprefix:
toc: right
toclevels: 1
guides: https://guides.gradle.org
gradle-version: 3.5
user-manual-name: User Manual
user-manual: https://docs.gradle.org/3.5/userguide/
language-reference: https://docs.gradle.org/3.5/dsl/
api-reference: https://docs.gradle.org/3.5/javadoc/
repo-path: gradle-guides/creating-multi-project-builds

Test JVM Code plugin

  • Adds groovy plugin, as well Spock Framework so that JVM code snippets can be tested.

  • Adds samples convention.

Samples convention

Samples code can be placed in src/samples/code and expected output in src/samples/output i.e.

.
└── samples
    ├── code
    └── output

These files can be accessed from test code via system property samplesDir.

They can also be accessed from Asciidoc documents via the {samplescodedir} and {samplesoutputdir} attributes.

Getting Started plugin

This should be applied in the authoring of all new Getting Started guides

Topical plugin

This should be applied in the authoring of all new Topical guides

Tutorial plugin

This should be applied in the authoring of all new Topical guides

Changelog

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 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. Wait for Travis CI to publish the plugins on the plugin portal.

  6. Create Github release.

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

You can’t perform that action at this time.