https://github.com/gradle/gradle-site-plugin
https://github.com/gradle/gradle-site-plugin
gradle-bt gradle-bt-documentation
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/gradle/gradle-site-plugin
- Owner: gradle
- License: apache-2.0
- Created: 2020-01-27T14:55:38.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-07-11T15:49:38.000Z (10 months ago)
- Last Synced: 2025-01-05T19:08:56.929Z (4 months ago)
- Topics: gradle-bt, gradle-bt-documentation
- Language: Kotlin
- Size: 481 KB
- Stars: 43
- Watchers: 33
- Forks: 69
- Open Issues: 4
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE.txt
Awesome Lists containing this project
README
:maven-metadata: plugins.gradle.org/m2/gradle/plugin/org/gradle/plugins/gradle-site-plugin
:travis: https://travis-ci.org/gradle-guides/gradle-site-plugin
:gradle-plugins-portal: https://plugins.gradle.org/plugin/gradle.site
= Gradle Site Plugin image:{travis}.svg?branch=master["Build Status", link="{travis}"] image:https://img.shields.io/badge/build-scan-green.svg["Build Scan", link="https://gradle.com/s/thgfe3dxihijo"] image:https://img.shields.io/maven-metadata/v/https/{maven-metadata}/maven-metadata.xml.svg?label=gradlePluginPortal["Maven Central",link="{gradle-plugins-portal}"]
A sample Gradle plugin demonstrating established techniques and practices for plugin development as described in the following guides:
- link:https://guides.gradle.org/designing-gradle-plugins/[Designing Gradle plugins]
- link:https://guides.gradle.org/implementing-gradle-plugins/[Implementing Gradle plugins]
- link:https://guides.gradle.org/testing-gradle-plugins/[Testing Gradle plugins]
== Functionality
The plugin provides a task for generating a web page that derives information about the project e.g. applied plugins and available tasks. While minimalistic in functionality it serves as a show case for demonstrating best practices for Gradle plugin development. A site generated for this project can be link:https://gradle-guides.github.io/gradle-site-plugin/[viewed here].
TIP: The plugin is link:{gradle-plugins-portal}[available on the Gradle plugin portal] for public consumption.
== Usage example
The plugin can be applied with by identifier `gradle.site`. Default values can be configured with the help of the provided extension `org.gradle.plugins.site.SitePluginExtension`. To generate the web page run the task named `generateSite` e.g. `gradle generateSiteHtml`.
IMPORTANT: The plugin requires a Gradle version of 4.0 or higher. All features that are based on Gradle 4.0 are explicitly
marked above. All other features will work with earlier versions of Gradle.
```
plugins {
id("gradle.site").version("0.6")
}
site {
outputDir.set(file("$rootDir/docs"))
websiteUrl.set("https://mysite.com")
vcsUrl.set("https://github.com/my/repo.git")
}
```
== Applied techniques and practices
- Production and test code written in Kotlin.
- Reusable logic written as binary plugin.
- Usage of the Plugin Development plugin to simplify plugin development. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/build.gradle.kts#L6[Code] | link:https://guides.gradle.org/implementing-gradle-plugins/#plugin-development-plugin[More Details]]
- Implementation of tasks as custom task type. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/src/main/kotlin/org/gradle/plugins/site/tasks/SiteGenerate.kt[Code] | link:https://guides.gradle.org/implementing-gradle-plugins/#writing-and-using-custom-task-types[More Details]]
- Usage of input and output properties to enable incremental tasks. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/src/main/kotlin/org/gradle/plugins/site/tasks/SiteGenerate.kt[Code] | link:https://guides.gradle.org/implementing-gradle-plugins/#benefiting_from_incremental_tasks[More Details]]
- Usage of an extension to capture user-configurable values. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/src/main/kotlin/org/gradle/plugins/site/SitePlugin.kt#L33[Code] | link:https://guides.gradle.org/designing-gradle-plugins/#convention_over_configuration[More Details]]
- Mapping of extension property values to custom task properties. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/src/main/kotlin/org/gradle/plugins/site/SitePlugin.kt#L74-L76[Code] | link:https://guides.gradle.org/implementing-gradle-plugins/#capturing_user_input_to_configure_plugin_runtime_behavior[More Details]] image:https://img.shields.io/badge/4.0-feature-blue.svg[4.0 feature]
- Reacting to plugins instead of applying plugins. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/src/main/kotlin/org/gradle/plugins/site/SitePlugin.kt#L64[Code] | link:https://guides.gradle.org/implementing-gradle-plugins/#reacting_to_plugins[More Details]]
- Declaration of appropriate plugin identifiers. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/src/main/resources/META-INF/gradle-plugins/gradle.site.properties[Code] | link:https://guides.gradle.org/implementing-gradle-plugins/#assigning_appropriate_plugin_identifiers[More Details]]
- Functional testing with TestKit. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/src/intTest/kotlin/org/gradle/plugins/site/SitePluginFunctionalTest.kt[Code] | link:https://docs.gradle.org/current/userguide/test_kit.html[More Details]]
- Publication of the plugin artifacts to the Gradle plugin portal [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/build.gradle.kts#L136-L163[Code] | link:https://guides.gradle.org/publishing-plugins-to-gradle-plugin-portal/[More Details]]
- Continuous Integration of plugin code with link:https://travis-ci.org/[Travis CI]. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/.travis.yml[Code] | More Details]
- Automatic generation of build scans when build is executed from CI. [link:https://github.com/gradle-guides/gradle-site-plugin/blob/master/build.gradle.kts#L25-L33[Code] | link:https://scans.gradle.com/[More Details]]