From 1b328d0d33cf34033d5c1b8e816eb5bded80c925 Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Mon, 4 Apr 2022 08:54:16 -0400 Subject: [PATCH 1/8] Mirror of Picard metrics documentation generation changes. --- .../help/GATKHelpDocWorkUnitHandler.java | 35 +++++++++- .../utils/helpTemplates/metrics.template.html | 69 +++++++++++++++++++ 2 files changed, 103 insertions(+), 1 deletion(-) create mode 100644 src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java index 098e81caf75..ef26e31a52f 100644 --- a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java +++ b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java @@ -1,10 +1,17 @@ package org.broadinstitute.hellbender.utils.help; +import com.sun.javadoc.FieldDoc; +import htsjdk.samtools.metrics.MetricBase; import org.broadinstitute.barclay.argparser.CommandLineProgramProperties; import org.broadinstitute.barclay.help.DefaultDocWorkUnitHandler; import org.broadinstitute.barclay.help.DocWorkUnit; import org.broadinstitute.barclay.help.HelpDoclet; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + /** * The GATK Documentation work unit handler class that is the companion to GATKHelpDoclet. * @@ -17,6 +24,12 @@ public class GATKHelpDocWorkUnitHandler extends DefaultDocWorkUnitHandler { private final static String GATK_JAVADOC_TAG_PREFIX = "GATK"; // prefix for custom javadoc tags used by GATK private final static String GATK_FREEMARKER_TEMPLATE_NAME = "generic.template.html"; + private final static String PICARD_METRICS_TEMPLATE_NAME = "metrics.template.html"; + + private final static String WORK_UNIT_SUMMARY_KEY = "summary"; + private final static String METRICS_MAP_ENTRY_KEY = "metrics"; + private final static String METRICS_MAP_NAME_KEY = "name"; + private final static String METRICS_MAP_SUMMARY_KEY = "summary"; public GATKHelpDocWorkUnitHandler(final HelpDoclet doclet) { super(doclet); @@ -35,7 +48,14 @@ public GATKHelpDocWorkUnitHandler(final HelpDoclet doclet) { * Javadoc. */ @Override - public String getTemplateName(final DocWorkUnit workUnit) { return GATK_FREEMARKER_TEMPLATE_NAME; } + public String getTemplateName(final DocWorkUnit workUnit) { + Class clazz = workUnit.getClazz(); + if (MetricBase.class.isAssignableFrom(clazz)) { + return PICARD_METRICS_TEMPLATE_NAME; + } else { + return GATK_FREEMARKER_TEMPLATE_NAME; + } + } /** @@ -54,6 +74,19 @@ protected void addCustomBindings(final DocWorkUnit currentWorkUnit) { if (picard.cmdline.CommandLineProgram.class.isAssignableFrom(toolClass)) { final CommandLineProgramProperties clpProperties = currentWorkUnit.getCommandLineProperties(); currentWorkUnit.setProperty("picardsummary", clpProperties.summary()); + } else if (MetricBase.class.isAssignableFrom(toolClass)) { + currentWorkUnit.setProperty(WORK_UNIT_SUMMARY_KEY, currentWorkUnit.getSummary()); + final List> workUnitMetricsList = new ArrayList<>(); + currentWorkUnit.setProperty(METRICS_MAP_ENTRY_KEY, workUnitMetricsList); + final FieldDoc[] fieldDocs = currentWorkUnit.getClassDoc().fields(false); + for (final FieldDoc fd : fieldDocs) { + if (fd.isPublic()) { + final Map metricsFields = new HashMap<>(); + metricsFields.put(METRICS_MAP_NAME_KEY, fd.name()); + metricsFields.put(METRICS_MAP_SUMMARY_KEY, fd.getRawCommentText()); + workUnitMetricsList.add(metricsFields); + } + } } } diff --git a/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html b/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html new file mode 100644 index 00000000000..3ad57fc6d82 --- /dev/null +++ b/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html @@ -0,0 +1,69 @@ + + + + +
+ + <#include "common.html"/> + + + +
+ + + + +
+ +
+ +

${name}

+ +

${summary}

+ + <#if group?? > +

Category + ${group} +

+ +
+

Overview

+ ${description} + + <#-- Create the metrics summary --> + <#if metrics?size != 0> +

This table summarizes the values that are specific to this metric.

+ + + + + + + + <#list metrics as metric> + + + + + +
MetricSummary
${metric.name}
+ 		${metric.summary}
+ + + <@footerInfo /> + <@footerClose /> + +
+ + \ No newline at end of file From accca6c2a497162770facdd5e5ad56009e7a0a43 Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Mon, 4 Apr 2022 09:14:04 -0400 Subject: [PATCH 2/8] Add DocumentedFeature. --- .../broadinstitute/hellbender/metrics/InsertSizeMetrics.java | 4 +++- .../hellbender/metrics/QualityYieldMetrics.java | 3 +++ .../hellbender/metrics/analysis/AlleleFrequencyQCMetric.java | 3 +++ .../metrics/analysis/BaseDistributionByCycleMetrics.java | 3 +++ .../tools/spark/pathseq/loggers/PSFilterMetrics.java | 3 +++ .../tools/spark/pathseq/loggers/PSScoreMetrics.java | 3 +++ 6 files changed, 18 insertions(+), 1 deletion(-) diff --git a/src/main/java/org/broadinstitute/hellbender/metrics/InsertSizeMetrics.java b/src/main/java/org/broadinstitute/hellbender/metrics/InsertSizeMetrics.java index ee97d032635..7c339a8838e 100644 --- a/src/main/java/org/broadinstitute/hellbender/metrics/InsertSizeMetrics.java +++ b/src/main/java/org/broadinstitute/hellbender/metrics/InsertSizeMetrics.java @@ -1,7 +1,8 @@ package org.broadinstitute.hellbender.metrics; import htsjdk.samtools.SamPairUtil.PairOrientation; -import org.broadinstitute.hellbender.metrics.MultiLevelMetrics; +import org.broadinstitute.barclay.help.DocumentedFeature; +import picard.util.help.HelpConstants; import java.io.Serializable; @@ -11,6 +12,7 @@ * ".insertSizeMetrics". In addition the insert size distribution is plotted to * a file with the extension ".insertSizeMetrics.pdf". */ +@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY) public final class InsertSizeMetrics extends MultiLevelMetrics implements Serializable { private static final long serialVersionUID = 1L; diff --git a/src/main/java/org/broadinstitute/hellbender/metrics/QualityYieldMetrics.java b/src/main/java/org/broadinstitute/hellbender/metrics/QualityYieldMetrics.java index 97733986065..a66be888a70 100644 --- a/src/main/java/org/broadinstitute/hellbender/metrics/QualityYieldMetrics.java +++ b/src/main/java/org/broadinstitute/hellbender/metrics/QualityYieldMetrics.java @@ -1,13 +1,16 @@ package org.broadinstitute.hellbender.metrics; import htsjdk.samtools.metrics.MetricBase; +import org.broadinstitute.barclay.help.DocumentedFeature; import org.broadinstitute.hellbender.utils.Utils; import org.broadinstitute.hellbender.utils.read.GATKRead; import org.broadinstitute.hellbender.utils.read.ReadUtils; +import picard.util.help.HelpConstants; import java.io.Serializable; /** A set of metrics used to describe the general quality of a BAM file */ +@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY) public final class QualityYieldMetrics extends MetricBase implements Serializable { private static final long serialVersionUID = 1; diff --git a/src/main/java/org/broadinstitute/hellbender/metrics/analysis/AlleleFrequencyQCMetric.java b/src/main/java/org/broadinstitute/hellbender/metrics/analysis/AlleleFrequencyQCMetric.java index 7159b7a2d41..4c128deaac9 100644 --- a/src/main/java/org/broadinstitute/hellbender/metrics/analysis/AlleleFrequencyQCMetric.java +++ b/src/main/java/org/broadinstitute/hellbender/metrics/analysis/AlleleFrequencyQCMetric.java @@ -1,7 +1,10 @@ package org.broadinstitute.hellbender.metrics.analysis; import htsjdk.samtools.metrics.MetricBase; +import org.broadinstitute.barclay.help.DocumentedFeature; +import picard.util.help.HelpConstants; +@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY) public class AlleleFrequencyQCMetric extends MetricBase { public String SAMPLE; diff --git a/src/main/java/org/broadinstitute/hellbender/metrics/analysis/BaseDistributionByCycleMetrics.java b/src/main/java/org/broadinstitute/hellbender/metrics/analysis/BaseDistributionByCycleMetrics.java index 5e96939eb96..7e846cbf7cd 100644 --- a/src/main/java/org/broadinstitute/hellbender/metrics/analysis/BaseDistributionByCycleMetrics.java +++ b/src/main/java/org/broadinstitute/hellbender/metrics/analysis/BaseDistributionByCycleMetrics.java @@ -1,7 +1,10 @@ package org.broadinstitute.hellbender.metrics.analysis; import htsjdk.samtools.metrics.MetricBase; +import org.broadinstitute.barclay.help.DocumentedFeature; +import picard.util.help.HelpConstants; +@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY) public final class BaseDistributionByCycleMetrics extends MetricBase { public int READ_END; public int CYCLE; diff --git a/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSFilterMetrics.java b/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSFilterMetrics.java index b97960a057c..827d31de69e 100644 --- a/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSFilterMetrics.java +++ b/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSFilterMetrics.java @@ -1,10 +1,13 @@ package org.broadinstitute.hellbender.tools.spark.pathseq.loggers; import htsjdk.samtools.metrics.MetricBase; +import org.broadinstitute.barclay.help.DocumentedFeature; +import picard.util.help.HelpConstants; /** * Metrics that are calculated during the PathSeq filter */ +@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY) public final class PSFilterMetrics extends MetricBase { /** diff --git a/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSScoreMetrics.java b/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSScoreMetrics.java index fb9300ca0fd..804e02779bb 100644 --- a/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSScoreMetrics.java +++ b/src/main/java/org/broadinstitute/hellbender/tools/spark/pathseq/loggers/PSScoreMetrics.java @@ -1,11 +1,14 @@ package org.broadinstitute.hellbender.tools.spark.pathseq.loggers; import htsjdk.samtools.metrics.MetricBase; +import org.broadinstitute.barclay.help.DocumentedFeature; +import picard.util.help.HelpConstants; /** * Metrics that are calculated during the PathSeq scoring */ @SuppressWarnings("serial") +@DocumentedFeature(groupName = HelpConstants.DOC_CAT_METRICS, summary = HelpConstants.DOC_CAT_METRICS_SUMMARY) public final class PSScoreMetrics extends MetricBase { /** From 9dc5fe7c9284e2283acd4db07b508d3544b56cd4 Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Tue, 5 Apr 2022 09:37:30 -0400 Subject: [PATCH 3/8] Suppress deprecation warning for FieldDoc usage. --- .../hellbender/utils/help/GATKHelpDocWorkUnitHandler.java | 1 + 1 file changed, 1 insertion(+) diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java index ef26e31a52f..8b80ff78e89 100644 --- a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java +++ b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java @@ -65,6 +65,7 @@ public String getTemplateName(final DocWorkUnit workUnit) { * @param currentWorkUnit the work unit for the feature being documented */ @Override + @SuppressWarnings("deprecation") protected void addCustomBindings(final DocWorkUnit currentWorkUnit) { super.addCustomBindings(currentWorkUnit); From 97153d525ee8f44daa3e7a846bd70784e78f4aed Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Mon, 2 May 2022 12:34:23 -0400 Subject: [PATCH 4/8] Suppress removal warning. --- .../hellbender/utils/help/GATKHelpDocWorkUnitHandler.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java index 8b80ff78e89..15e6b2ee9bb 100644 --- a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java +++ b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java @@ -65,7 +65,7 @@ public String getTemplateName(final DocWorkUnit workUnit) { * @param currentWorkUnit the work unit for the feature being documented */ @Override - @SuppressWarnings("deprecation") + @SuppressWarnings({"deprecation","removal"}) protected void addCustomBindings(final DocWorkUnit currentWorkUnit) { super.addCustomBindings(currentWorkUnit); From 984d405a424bca7ab759a656814285f25a589606 Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Mon, 2 May 2022 14:37:15 -0400 Subject: [PATCH 5/8] Suppress import. --- .../hellbender/utils/help/GATKHelpDocWorkUnitHandler.java | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java index 15e6b2ee9bb..8c45f12b18c 100644 --- a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java +++ b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java @@ -1,6 +1,5 @@ package org.broadinstitute.hellbender.utils.help; -import com.sun.javadoc.FieldDoc; import htsjdk.samtools.metrics.MetricBase; import org.broadinstitute.barclay.argparser.CommandLineProgramProperties; import org.broadinstitute.barclay.help.DefaultDocWorkUnitHandler; @@ -79,8 +78,8 @@ protected void addCustomBindings(final DocWorkUnit currentWorkUnit) { currentWorkUnit.setProperty(WORK_UNIT_SUMMARY_KEY, currentWorkUnit.getSummary()); final List> workUnitMetricsList = new ArrayList<>(); currentWorkUnit.setProperty(METRICS_MAP_ENTRY_KEY, workUnitMetricsList); - final FieldDoc[] fieldDocs = currentWorkUnit.getClassDoc().fields(false); - for (final FieldDoc fd : fieldDocs) { + final com.sun.javadoc.FieldDoc[] fieldDocs = currentWorkUnit.getClassDoc().fields(false); + for (final com.sun.javadoc.FieldDoc fd : fieldDocs) { if (fd.isPublic()) { final Map metricsFields = new HashMap<>(); metricsFields.put(METRICS_MAP_NAME_KEY, fd.name()); From f9264a81b59870f93a6adfffa6004ca36d52bd99 Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Tue, 7 Mar 2023 09:00:17 -0500 Subject: [PATCH 6/8] Use new APIs. --- .../help/GATKHelpDocWorkUnitHandler.java | 28 ++++++++++++++----- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java index 8c45f12b18c..c9dd78da536 100644 --- a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java +++ b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java @@ -5,7 +5,12 @@ import org.broadinstitute.barclay.help.DefaultDocWorkUnitHandler; import org.broadinstitute.barclay.help.DocWorkUnit; import org.broadinstitute.barclay.help.HelpDoclet; +import org.broadinstitute.barclay.help.scanners.JavaLanguageModelScanners; +import javax.lang.model.element.Element; +import javax.lang.model.element.ElementKind; +import java.lang.reflect.Field; +import java.lang.reflect.Modifier; import java.util.ArrayList; import java.util.HashMap; import java.util.List; @@ -78,13 +83,22 @@ protected void addCustomBindings(final DocWorkUnit currentWorkUnit) { currentWorkUnit.setProperty(WORK_UNIT_SUMMARY_KEY, currentWorkUnit.getSummary()); final List> workUnitMetricsList = new ArrayList<>(); currentWorkUnit.setProperty(METRICS_MAP_ENTRY_KEY, workUnitMetricsList); - final com.sun.javadoc.FieldDoc[] fieldDocs = currentWorkUnit.getClassDoc().fields(false); - for (final com.sun.javadoc.FieldDoc fd : fieldDocs) { - if (fd.isPublic()) { - final Map metricsFields = new HashMap<>(); - metricsFields.put(METRICS_MAP_NAME_KEY, fd.name()); - metricsFields.put(METRICS_MAP_SUMMARY_KEY, fd.getRawCommentText()); - workUnitMetricsList.add(metricsFields); + final Field[] fields = currentWorkUnit.getClazz().getFields(); + for (final Field field : fields) { + if (Modifier.isPublic(field.getModifiers())) { + final Element fieldElement = JavaLanguageModelScanners.getElementForField( + getDoclet().getDocletEnv(), + currentWorkUnit.getDocElement(), + field, + ElementKind.FIELD + ); + if (fieldElement != null) { + final String docComment = JavaLanguageModelScanners.getDocComment(getDoclet().getDocletEnv(), fieldElement); + final Map metricsFields = new HashMap<>(); + metricsFields.put(METRICS_MAP_NAME_KEY, field.getName()); + metricsFields.put(METRICS_MAP_SUMMARY_KEY, docComment); + workUnitMetricsList.add(metricsFields); + } } } } From c80f9f9d298b496a1e3bb9b396f611c4bc91858c Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Mon, 13 Mar 2023 15:13:23 -0400 Subject: [PATCH 7/8] Remove the groups list from the metrics detail page so it matches the other detail pages. --- .../hellbender/utils/help/GATKHelpDocWorkUnitHandler.java | 2 +- .../hellbender/utils/helpTemplates/metrics.template.html | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java index c9dd78da536..1b6d9dbedcc 100644 --- a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java +++ b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java @@ -47,7 +47,7 @@ public GATKHelpDocWorkUnitHandler(final HelpDoclet doclet) { /** * @param workUnit the classdoc object being processed - * @return the name of a the freemarker template to be used for the class being documented. + * @return the name of the freemarker template to be used for the class being documented. * Must reside in the folder passed to the Barclay Doclet via the "-settings-dir" parameter to * Javadoc. */ diff --git a/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html b/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html index 3ad57fc6d82..3a199f78fdf 100644 --- a/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html +++ b/src/main/resources/org/broadinstitute/hellbender/utils/helpTemplates/metrics.template.html @@ -18,10 +18,6 @@ - From f99ced2890cd821a54531032df7c4fe0ecfec8e5 Mon Sep 17 00:00:00 2001 From: Chris Norman Date: Tue, 14 Mar 2023 12:44:18 -0400 Subject: [PATCH 8/8] One review comment fix - remove no longer needed SuppressWarnings. --- .../hellbender/utils/help/GATKHelpDocWorkUnitHandler.java | 1 - 1 file changed, 1 deletion(-) diff --git a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java index 1b6d9dbedcc..ec6cb4854ac 100644 --- a/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java +++ b/src/main/java/org/broadinstitute/hellbender/utils/help/GATKHelpDocWorkUnitHandler.java @@ -69,7 +69,6 @@ public String getTemplateName(final DocWorkUnit workUnit) { * @param currentWorkUnit the work unit for the feature being documented */ @Override - @SuppressWarnings({"deprecation","removal"}) protected void addCustomBindings(final DocWorkUnit currentWorkUnit) { super.addCustomBindings(currentWorkUnit);