Merge pull request #76 from jenkinsci/docu

adjust documentation for new plugin api

Author: simonsymhoven

README.md

@@ -38,7 +38,6 @@ An example json file looks like this:
 ```
 {
   "id": "my-json-report"
-  "name": "My JSON report"
   "items": [
     {
       "id": "stocks",
@@ -106,12 +105,11 @@ To check your json you can use the [json schema](src/main/resources/report.json)
 
 > ⚠️ **Color Mapping**:
 > 
-> You can provide a color mapping. Then, please make sure, that the attribute `colors needs exactly the same 
+> You can provide a color mapping. Then, please make sure, that the attribute `colors` needs exactly the same 
 > attributes as the result of the items and assigns a color to each attribute, which is used for the graphical representation. 
 > Otherwise a default color `#E9E9E9` is used for the missing property! 
-> 
-> If no `colors` object is provided, 
-> a color palette will be calculated. You can use own HEX values or the following predefined colors are supported:
+>
+> You can use own HEX values or the following predefined colors are supported:
 > * YELLOW
 > * LIME 
 > * GREEN
@@ -124,6 +122,8 @@ To check your json you can use the [json schema](src/main/resources/report.json)
 > * BROWN
 > * GRAY
 > * WHITE
+> 
+> If no `colors` object is provided, a color palette will be calculated.
 
 If your items only have one result, the visualization is different from the default one, 
 because the representation then makes no sense. Instead of the attributes of the result object, 
@@ -132,7 +132,6 @@ the keys of the individual items are used as the basis for distribution. For exa
 ```
 {
   "id": "my-second-json-report"
-  "name": "My second JSON report"
   "items": [
     {
       "id": "Aktie",
@@ -221,8 +220,6 @@ Then your dashboard looks like this:
 * XML
 * CSV
 
-For examples of report files, please have look into [etc](/etc) folder.
-
 ### Visualization
 
 At job level, a trend chart is generated showing the development 
@@ -242,21 +239,37 @@ available in the json model. On the lowest level only the pie chart and the hist
 
 ### Pipeline Step
 
+For examples of report files and pipelines, please have look into [etc](/etc) folder.
+
 ```
-publishReport pattern: "**/result-*.json", displayType: "absolute"
+publishReport name: "JSON Report", displayType: "dual", provider: json(pattern: "etc/report-1-part-*.json")
+publishReport name: "XML Report", displayType: "dual", provider: xml(pattern: "etc/*.xml")
+publishReport name: "YAML Report", displayType: "dual", provider: yaml(pattern: "etc/*.yaml")
+publishReport name: "CSV Report", displayType: "dual", provider: csv(id: "csv-one", pattern: "etc/*.csv")
 ```
 
 ### Parameter: 
 
-##### pattern: 
+#### name:
+Choose a name for the report. The name is shown in the UI.
 
-This is an ant include pattern for the files should be parsed and scanned (see Patterns in the Apache Ant Manual). 
-Multiple includes can be specified by separating each pattern with a comma.
-At the moment only yaml/yml or json files are supported.
+#### displayType (optional, default = `absolute`):
+This can be used to change the display of the displayed metrics within the distribution table.
+'absolute' shows the absolute values from the underlying files. 'relative', shows percentage values
+and 'dual' shows the absolute value and additionally the relative frequency within the category.
+
+#### provider:
+Choose a provider that should find and parse the files based on the given pattern.
+If all files found have the same ID and can be structurally merged, they are merged into one report.
+The id of the first report file found will be used as master id. All following reports of the pattern must match it, otherwise 
+they are ignored.
 
-##### displayType (optional, default = `absolute`):
-This can be used to determine the representation of the values within the table.
-Choose between `absolute`, `relative` or `dual`.
+##### id (only required for CSV provider):
+Specify the id of the report to tag the result and to find reports of past builds. Just required for CSV provider.
+
+##### pattern:
+This is an ant include pattern for the files should be parsed and scanned (see Patterns in the Apache Ant Manual).
+Multiple includes can be specified by separating each pattern with a comma.
 
 ## Issues
 

etc/Jenkinsfile

@@ -5,7 +5,8 @@ pipeline {
 		stage('Publish Data') {
 			steps {
 				checkout scm
-				publishReport name: "JSON Report", displayType: "dual", provider: json(pattern: "etc/report-1-part-*.json")
+				publishReport name: "First JSON Report", displayType: "dual", provider: json(pattern: "etc/report-1-part-*.json")
+				publishReport name: "Second JSON Report", displayType: "dual", provider: json(pattern: "etc/report-2.json")
 				publishReport name: "XML Report", displayType: "dual", provider: xml(pattern: "etc/*.xml")
 				publishReport name: "YAML Report", displayType: "dual", provider: yaml(pattern: "etc/*.yaml")
 				publishReport name: "CSV Report", displayType: "dual", provider: csv(id: "csv-one", pattern: "etc/*.csv")

etc/report-2.json

@@ -0,0 +1,19 @@
+{ 
+  "id": "report-two",
+  "items": [
+    {
+      "id": "Aktie",
+      "name": "Aktie",
+      "result": {
+        "incorrect": 3441,
+        "manually": 348,
+        "accurate": 5199
+      }
+    }
+  ],
+  "colors": {
+    "incorrect": "#EF9A9A",
+    "manually": "#FFF59D",
+    "accurate": "#A5D6A7"
+  }
+}

etc/ui-3.8.0-oc.png

@@ -1,6 +1,7 @@
 package io.jenkins.plugins.reporter.model;
 
 import com.google.errorprone.annotations.FormatMethod;
+import org.apache.commons.io.FilenameUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.exception.ExceptionUtils;
 
@@ -105,18 +106,20 @@ public void add(Report report) {
 
         if (StringUtils.isEmpty(id)) {
             setId(report.getId());
-            logInfo("Add first report. Set ID='%s'", report.getId());
+            logInfo("First added report. Set ID='%s'", report.getId());
         }
 
         if (getId().equals(report.getId())) {
+            logInfo("Add report with ID='%s'.", report.getId());
+            
             this.subReports.add(report);
             this.infoMessages.addAll(report.getInfoMessages());
             this.errorMessages.addAll(report.getErrorMessages());
             addColors(report.getColors());
             addItems(report.getItems());
             logInfo("Successfully added report with ID='%s'", report.getId());
         } else {
-            logError("Skip adding report because ID='%s' is different from parent ID='%s'.", 
+            logInfo("Skip adding report with ID='%s' because it does not match parent ID='%s'.", 
                     report.getId(), getId());
         }
     }

etc/ui-3.8.0.png

@@ -71,9 +71,8 @@ private void aggregateReport(final Path file, final Report aggregatedReport) {
         try {
             Report report = parser.parse(file.toFile()).toReport();
             aggregatedReport.logInfo("Successfully parsed file %s", file);
-            aggregatedReport.logInfo("Add report with ID='%s' and filename NAME='%s'.", 
-                    report.getId(), FilenameUtils.getName(file.toString()));
             aggregatedReport.add(report);
+            
         } catch (IOException exception) {
             aggregatedReport.logException(exception, "Parsing of file '%s' failed due to an exception:", file);
         }

src/main/java/io/jenkins/plugins/reporter/model/Report.java

@@ -1,14 +1,14 @@
 <?jelly escape-by-default='true'?>
 <j:jelly xmlns:j="jelly:core" xmlns:c="/controls" xmlns:f="/lib/form">
 
-    <f:entry name="id" title="${%Id}" field="id">
+    <f:entry name="id" title="${%Id}" field="id" description="${%id.description}">
 
         <f:textbox/>
 
     </f:entry>
 
     <f:entry title="${%Pattern}" field="pattern"
-              description="${%description.patternRequired('http://ant.apache.org/manual/Types/fileset.html')}">
+              description="${%pattern.description('http://ant.apache.org/manual/Types/fileset.html')}">
 
         <c:safe-textbox/>
 

src/main/java/io/jenkins/plugins/reporter/util/FilesScanner.java

@@ -1,3 +1,4 @@
-description.patternRequired=<a href="{0}">Fileset ''includes''</a> syntax \
+pattern.description=<a href="{0}">Fileset ''includes''</a> syntax \
     specifying the files to scan for reports, \
-    such as ''**/target/report.json''.
+    such as ''**/target/report.json''.
+id.description=ID of this provider, it must be unique to tag the report and retrieve reports of past builds.

src/main/resources/io/jenkins/plugins/reporter/model/Provider/config.jelly

@@ -0,0 +1,5 @@
+<div>
+    Normally the ID of the report is read via the underlying file. With a CSV provider this is not possible, 
+    because in a csv file you have no possibility to specify it in a structured way. 
+    Therefore the CSV provider needs an ID to tag the read report and to find reports of past builds to create the history.
+</div>