1 Project Reports

1.1 Test Reports

1.2 Static Code Analyzers

Many tools that we will cover later for analyzing code can produce useful (or at least, impressive) documentation as a side effect.

1.3 Configuration Reports

Configuration managers generate reports about the dependencies among the software components.

2 Project Websites

2.1 Case study: Constructing a project website with Gradle

Let’s look at the process of building a simple website that provides

2.1.1 Build plan

After a build, we can construct a website in build/reports by

1. Copying build/doc/ into build/website

   • This gets a copy of the Javadocs

   • Note that the JUnit and project configuration reports will already be in subdirectories of build/reports.

2. Copying HTML, CSS, and Javascript files from src/main/html into reports.

   • Hand-crafted pages with the project description and links to the three reports.

2.1.2 The HTML File

2.1.3 Gradle setup

After a build, we can construct a website in build/reports by

1. Copying build/doc/ into build/website
2. Copying HTML, CSS, and Javascript files from src/main/html into reports.

   test.ignoreFailures=true                ➀
   check.dependsOn htmlDependencyReport    ➁
   
   task copyWebPages (type: Copy) {        ➄
       from 'src/main/html'
       into 'build/reports'
   }
   
   task copyDocs (type: Copy) {            ➃
       from 'build/docs'
       into 'build/reports/docs'
       dependsOn 'javadoc'
   }
   
   task buildSite (dependsOn: ['javadoc', 'check',             ➂
                         'copyWebPages', 'copyDocs']) {
       description 'Generate reports website for this project'
   }
   

• ➀ Don’t want the build to stop just because some unit tests are failing

  • In TDD, some tests are almost always failing
  • One reason for posting the JUnit report is so that people can see what we fail and what we pass.

• ➁ Force the generation of the configuration report whenever we build the check target/task.

• ➂ Here’s our new target, buildSite.

  It has no actions of its own, but the depedencies force everything else to happen.

• ➃ Here’s step 1 of our process: copying the docs into the website

• ➄ Here’s step 2 of our process: copying the hand-crafted content from src/html into the website

2.2 Case study: Constructing a project website with Gradle and Jbake

2.2.1 Gradle & Jbake

Gradle has a jbake plugin that adds a bake task to generate a website.

• By default looks for source files in src/jbake
• By default writes the site into build/jbake

  buildscript {
         ⋮
      dependencies {
         ⋮
         classpath "org.jbake:jbake-gradle-plugin:5.0.0"
      }
  }
  
  ⋮
  apply plugin: 'org.jbake.site'
  

2.2.2 The website setup

src
├── jbake
│   ├── assets
│   │   ├── css
│   │   │   └── base.css
│   │   └── js
│   │       └── jquery-1.11.1.min.js
│   ├── content
│   │   ├── dependencies.html
│   │   ├── home0.md
│   │   ├── javadoc.html
│   │   └── junit.html
│   ├── jbake.properties
│   └── templates
│       ├── footer.ftl
│       ├── header.ftl
│       ├── index.ftl
│       ├── menu.ftl
│       ├── page.ftl
│       └── sitemap.ftl

The content directory` holds the actual information we want to disseminate.

The templates directory determines the “look and feel” of the website.

• The key template is page.ftl
• Every content file will be rendered using this page tempalte.

Templates:

2.2.3 Build Steps

To generate a website in build/jbake

1. Copy the build/reports and build/docs to build/tmp/website
2. Copy src/jbake to build/tmp/website
3. Concatenate build/tmp/website/content/home0.md and the project README.md to form build/tmp/website/content/home.md
4. Run Jbake on build/tmp/website/content/home.md to generate the full website in build/jbake

In build.gradle:

2.3 Publishing to a website

The case studies above will build a website, but we still need to upload that to a web server.

• Problems are not unlike publishing libraries to repositories.

2.3.1 Gradle: ssh solution

Gradle plugin org.hidetake:gradle-ssh-plugin allows you to

• Use scp to upload or download one file at a time from/to a remote server.
• Use ssh to issue commands to a remote server.

A plausible set of Gradle steps:

1. Create a .zip file of the entire constructed website
2. Use scp to upload the zip file to the remote server.
3. Use ssh to issue an unzip command on the remote server.
4. If necessary, use ssh to issue chmod commands as necessary on the unzipped content.

plugins {
  id 'org.hidetake.ssh' version '2.9.0'
}

task zipWebsite (type: Zip, dependsOn: 'bake') {   ➀
    archiveFileName = 'website.zip'
    destinationDirectory = file('build')
    from 'build/jbake'
}

remotes {
  webServer {
    host = IP address
    user = userName
    identity = file(ssh-private-key)  ➁
  }
}

task deploy (dependsOn: 'zipWebsite') {
  doLast {
    ssh.run {
      session(remotes.webServer) {
       put from: 'build/website.zip', into: 'websitePath' ➂
       execute 'unzip websitePath/website.zip' -d websitePath➃
      }
    }
  }
}

• ➀ zip up the website (assuming our earlier Jbake example)
• ➁ assumes this key is in a running key agent (or passphrase-free)
• ➂ Copy the zip file to the remote host
• ➃ Tell the remote host to unpack the zip file

2.3.2 Gradle: rsync solution

This approach can be used with the rsync-based file drops set up in earlier labs & assignments.

The Java library rsync4j-all provides a Java interface to rsync: