The Site Plugin

Remember the Maven site plugin? The one that used to look like this but now looks nice like this?

Yeah I do too, and I miss it. Gradle really doesn't provide anything like this. Good news! There are so many people that attempted it. Bad news! Most of them failed attempts and are dead and abandoned.

So I took a stab at it and borrowed from some of the half working projects and heavily from maven, bootstrap, the work of others, bookies, loan sharks, thieves and the Elders of Canterbury, simplifying things where ever possible.

Well it's not exactly the Maven Site Plugin, but it's our version of it. It's pretty darn close. It uses theming inspired by Apache Fluido and is loosely based on the work Paul Speed-2 @ filament did over here.

Instead of the APT based sites, we opted for a simpler solution, a singular page template which is then merged with generated content and your content using Markdown and the Common Mark renderer. We also looked at Pegdown but ran into performance issues. Asciidoc/docbook

Design

The Site Plugin (and sorry for stealing, I mean borrowing, err.. leveraging the name) uses a basic template file to produce the majority of the content. The template is then populated by a number of environment variables, the gradle.properties file, the dynamic menu generation, and finally, the content.

The content comes from internally generated content that is generally useful to developers (all the good old Project Information stuff that Maven's plugin does), and from the stuff you provide in the form of Markdown or Asciidoc.

Using the Site Plugin

Note: as of 1.0.14 this isn't necessary. The site plugin will auto download what you need. But if you're disconnected from the internet on the first run, it will probably fail. In which case, you should follow this procedure or clone gradle fury and host it in your environment.

1 .In the root of your project make the following directory structure

src
src/site
src/site/index.md

2 .Next you'll want to grab all the junk that's in Gradle-Fury's src/site folder. You really just need the img,css, and js folders.

3. Make a index.md

It is required! This is your splash page for your project. Make a good first impression! Note: if you're looking for gradle-fury's index.md page, you won't find it. Instead, we copy this readme.md to the right place and rename it. 4. In your root build.gradle adding the following

apply from 'https://raw.githubusercontent.com/gradle-fury/gradle-fury/master/gradle/site.gradle'

5. Build your project normally. We suggest running all possible tasks that generate reports, such as connectedCheck or if you are you using the Quality Plugin just call build.

6. Build the site with gradlew site. The output normally goes to root/build/site. The output location can be overridden by putting this in the root build.gradle file

ext.buildWebsiteDir = rootDir.absolutePath + "/docs/"

Dependencies

The Site plugin only requires that you have a gradle.properties present and populated with the pom settings. These are used to generate a number of the pages, such as licenses, name, description, urls, issue trackers, etc

Adding custom content

Simply place any custom HTML, Markdown, Asciidoc or PDF docs in the src/site and they will be included in the site build and linked in the left hand side nav menu.

Gradle-Fury's site's plugin can also use Github styled Markdown and Asciidoc formatted docs. These docs are rendered down to HTML and injected into the same template as the rest of the site.

Most Github flavored markdown tags are supported. You can also any files put in src/site/ will be included in the site. Any html or pdf files in the root src/site/ will be auto-linked on the left hand site navigation menu. We also have some magic to resolve relative links from markdown to markdown pages, but only if the article link doesn't have any spaces in it.

Changing the site logo

Replace the img/logo.png with whatever you want.

Customizing the site

Well, you have direct access to modify the template. Do whatever you want!

What's missing?

• Breadcrumbs
• Per module site configurations (right now, it's just a composite for the whole project)
• No deployment tasks
• Many of the pages the Maven Site Plugin generates can be reduced to just a link. For instance, the location of the source (do we really need an entire web page that only shows the link to the source code?). Same goes for CI, distro management and issue tracking.

What libraries are we using?

• jQuery - https://jquery.com/
• Twitter's Bootstrap - http://getbootstrap.com/2.3.2/
• Bootstrap Sortable - https://github.com/drvic10k/bootstrap-sortable
• Apache Fluido - original site
• Based on Paul Speed @ filament https://sourceforge.net/p/filament/code/HEAD/tree/trunk/site/build.gradle

How do we build the gradle-fury site?

./gradlew install -Pprofile=ci
# if needed, for distribution projects
./gradlew distZip -Pprofile=ci
# if needed, for on device android test and reports
./gradlew cC
# finally, generate the site
./gradlew site -Pprofile=ci

The output goes to rootDir/build/site/

What is generated by the site plugin?

Here's a quick list

• Project Summary, all of the artifacts of your project, derived from the project itself and gradle.properties
• Project Team, from gradle.properties
• Links to the source, issue tracker, CI and distribution pages
• All javadocs are included and linked
• Project repository list, from gradle.properties
• Dependency report - for all the artifacts of your project, derived from the project itself
• Project reports - for all artifacts of the project, any and all things from the build/reports folder is included and linked (see the quality plugin). Includes test reports, connectedCheck, Findbugs, PMD, etc
• Converts and themes all your .md and .asciidoc files from the root/src/site and links them in

Notes of a madman

If you're really bored, continue to the next section. This bit is all about what I found difficult with this task.

Task order is a challenge - figuring out in what order to scan for stuff, generate content and populate content was tricky to get right. I finally ended up with a working solution that performs the following

1. Copy and record the Javadocs - this part is tricky with build variants and product flavors
2. Copy and record the Reports - this part was super hard, but gradle is dumb
3. Copy user content and templates - just a copy task
4. Generate then Navigation Menu - builds the left hand side nav menu
5. Prepare Template - prepares the template with all environment variables replaced, including the menu
6. GenerateCannedContent - this builds all of the stuff maven usually does for you, in markdown
7. Convert Content - converts all markdown and ascii doc stuff into html and removes the sources from the build directory, using the template.

Regarding the dumb part, gradle as 0 governance on build reports. As such, I had to write a lot of stupid fragile code that's plugin specific and java vs android specific, and android normal vs android with flavors/variants. The folder structures are inconsistent and there's no naming conventions for anything. I hate it.

Using the Dependency Converage report to sync for offline building

This part has to be done with Maven since gradle's caches are not portable.

Make a pom.xml and then copy and paste the maven composite dependency data in that the site generates. Then run maven mvn dependency:go-offline dependency:sources dependency:resolve -Dclassifier=javadoc

It may fail for android specific libraries that are included with the SDK. Manually remove those dependencies from the pom and retry until you get everything.