1 There is More to Documentation…

Documentation includes more than just writing inline code comments and using Javadoc (Java), Pydoc (Python), Rustdoc (Rust), or another tool for API documentation. Documentation includes reports, e.g.,

• JUnit Test Results
• Unit Test Coverage
• Integration Test Coverage
• Combined Test Coverage
• Dependency Reports (e.g., libraries used to build a project)
• API Documentation
• Static Analysis Reports (e.g., PMD and Spotbugs)

A few of these tools (especially Jacoco, PMD, and Spotbugs) are covered in the next module (Analysis Tools).

2 A Case Study

Recently (during April 2020) I updated one of my CS 330 (Object Oriented Programming and Design) Java examples.

2.1 Project Structure

Take a quick look at the project structure. There are quite a few pieces. Take a few moments to look at the “big picture.”

Example 1: Java Shapes Directory Structure

├── build
├── build.gradle
├── config
│   ├── checkstyle
│   │   └── checkstyle.xml
│   └── documentation.config
├── documentation.htm
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradle.properties
├── gradlew
├── gradlew.bat
└── src
    ├── integrationTest
    │   └── java
    │       └── edu
    │           └── odu
    │               └── cs
    │                   └── cs330
    │                       └── examples
    │                           └── shapes
    │                               ├── io
    │                               │   └── TestShapeIterator.java
    │                               └── TestShapeFactory.java
    ├── jbake
    │   ├── assets
    │   │   └── css
    │   │       └── base.css
    │   ├── content
    │   │   ├── checkstyle.md
    │   │   ├── coverageIntegration.md
    │   │   ├── coverage.md
    │   │   ├── coverageMerged.md
    │   │   ├── dependencies.md
    │   │   ├── home0.md
    │   │   ├── junitIntegration.md
    │   │   ├── junit.md
    │   │   ├── pmd.md
    │   │   ├── spotbugs.md
    │   │   └── tasks.md
    │   ├── jbake.properties
    │   └── templates
    │       ├── footer.ftl
    │       ├── header.ftl
    │       ├── index.ftl
    │       ├── menu.ftl
    │       ├── page.ftl
    │       ├── reportPage.ftl
    │       └── sitemap.ftl
    ├── main
    │   ├── java
    │   │   └── edu
    │   │       └── odu
    │   │           └── cs
    │   │               ├── cs330
    │   │               │   └── examples
    │   │               │       ├── package-info.java
    │   │               │       ├── RunShapes.java
    │   │               │       └── shapes
    │   │               │           ├── Circle.java
    │   │               │           ├── EquilateralTriangle.java
    │   │               │           ├── io
    │   │               │           │   ├── package-info.java
    │   │               │           │   └── ShapeIterator.java
    │   │               │           ├── package-info.java
    │   │               │           ├── RightTriangle.java
    │   │               │           ├── ShapeFactory.java
    │   │               │           ├── Shape.java
    │   │               │           ├── Square.java
    │   │               │           └── Triangle.java
    │   │               └── tkennedy
    │   │                   └── utilities
    │   │                       ├── package-info.java
    │   │                       └── Utilities.java
    │   └── resources
    │       └── inputShapes.txt
    └── test
        └── java
            └── edu
                └── odu
                    └── cs
                        └── cs330
                            └── examples
                                └── shapes
                                    ├── TestCircle.java
                                    ├── TestEquilateralTriangle.java
                                    ├── TestRightTriangle.java
                                    ├── TestSquare.java
                                    └── TestTriangle.java

2.2 JBake Directory Structure

We are interested in src/jbake.

Example 3: JBake src Files

└── src
    ├── jbake
    │   ├── assets
    │   │   └── css
    │   │       └── base.css
    │   ├── content
    │   │   ├── checkstyle.md
    │   │   ├── coverageIntegration.md
    │   │   ├── coverage.md
    │   │   ├── coverageMerged.md
    │   │   ├── dependencies.md
    │   │   ├── home0.md
    │   │   ├── junitIntegration.md
    │   │   ├── junit.md
    │   │   ├── pmd.md
    │   │   ├── spotbugs.md
    │   │   └── tasks.md
    │   ├── jbake.properties
    │   └── templates
    │       ├── footer.ftl
    │       ├── header.ftl
    │       ├── index.ftl
    │       ├── menu.ftl
    │       ├── page.ftl
    │       ├── reportPage.ftl
    │       └── sitemap.ftl

JBake has a few pieces:

2.2.1 jbake.propertes

JBake uses the ... before and after the settings to mark the beginning and end. The ... must be present.

...
render.index=true
render.archive=false
render.feed=false
render.tags=false
render.sitemap=false
template.reportPage.file=reportPage.ftl
markdown.extensions=-HARDWRAPS
...

The render. settings are built-in to JBake. Each such settings is set to true to enable generation of a page or false to disable generation of a page.

The template.reportPage setting specifies which layout file corresponds to my custom report page template.

The markdown.extensions setting allows markdown settings to be changes. In the case -=HARDWRAPS tells JBake to ignore any hardcoded line breaks in content files.

2.2.2 JBake Templates

In software engineering there exist a few mantras. One is D.R.Y (Don’t repeat yourself). Each report page (e.g., checkstyle.md) shares the same basic structure. After a little trial and error, I came up with the current version of reportPage.ftl.

Example 4: reportPage.ftl

<#include "header.ftl">

    <div class="row h-100">
        <div class="col-sm-3 col-md-2 bg-light hidden-md-down" id="main-nav">
        <#include "menu.ftl">
        </div>

        <div class="col">
            <div class="mh-90">
                <div class="pageHeader">
                    <h1><#escape x as x?xml>${content.title}</#escape></h1>
                </div>
                <p><em>${content.date?string("dd MMMM yyyy")}</em></p>

                ${content.body}

                <div class="embed-responsive ${content.report_iframe_aspectratio}">
                    <iframe class="embed-responsive-item" src="${content.report_file}" allowfullscreen> </iframe>
                </div>
            </div>
        </div>
    </div>


<#include "footer.ftl">

Most of the CSS classes (e.g., col-sm-3) come from Bootstrap helpers. Pay particular attention to pieces in the form ${...}. These are variables. They are replaced based on metadata located in a content file. Consider src/content/junit.md.

Example 5: Content Page

title=Java Shapes Example - Unit Tests
type=reportPage
status=published
report_file=tests/test/index.html
report_iframe_aspectratio=embed-responsive-4by3
~~~~~~

In this case, junit.md only contains metadata. I could add additional content under the ~~~~~~ (yes, the number of tildas is important).

• title - page title.
• type - type of page to generate (i.e., which template to use).
• status - set to published for every “active” page.
• report_file - which HTML report file (e.g., JUnit) to embed in the generated page.
• report_iframe_aspectratio - the bootstrap CSS class to use for the embedded report (determines the aspect ratio of the embedded report).

2.3 Gradle Updates

So far… we have only looked at the JBake directory and file structure. How do we update build.gradle? Take a quick look at the complete build.gradle. There is quite a bit going on, including:

• test configuration
• analysis tool configuration
• custom Gradle tasks