From 5b74763096635bdb4d777ce0645384e2dfa1a230 Mon Sep 17 00:00:00 2001 From: Roger Zurawicki Date: Tue, 24 Jul 2012 16:52:06 -0400 Subject: [PATCH] Removed Categories. We will use DocumentedGATKFeatures to create categories in our documentation. Eric I guess will be in charge of this. We need to remove walkers and think how to categorize everything. Tools can be hidden from GATKdocs with the @Hidden annotation Signed-off-by: Mauricio Carneiro --- .../broadinstitute/sting/gatk/Categorize.java | 38 ------ .../broadinstitute/sting/gatk/Category.java | 68 ----------- .../sting/utils/help/GATKDocWorkUnit.java | 12 +- .../sting/utils/help/GATKDoclet.java | 113 +++--------------- .../help/GenericDocumentationHandler.java | 2 +- settings/helpTemplates/common.html | 41 +++---- .../helpTemplates/generic.index.template.html | 61 +++++----- settings/helpTemplates/generic.template.html | 28 ++--- 8 files changed, 77 insertions(+), 286 deletions(-) delete mode 100644 public/java/src/org/broadinstitute/sting/gatk/Categorize.java delete mode 100644 public/java/src/org/broadinstitute/sting/gatk/Category.java diff --git a/public/java/src/org/broadinstitute/sting/gatk/Categorize.java b/public/java/src/org/broadinstitute/sting/gatk/Categorize.java deleted file mode 100644 index b8a222983..000000000 --- a/public/java/src/org/broadinstitute/sting/gatk/Categorize.java +++ /dev/null @@ -1,38 +0,0 @@ -/* - * Copyright (c) 2012, The Broad Institute - * - * Permission is hereby granted, free of charge, to any person - * obtaining a copy of this software and associated documentation - * files (the "Software"), to deal in the Software without - * restriction, including without limitation the rights to use, - * copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the - * Software is furnished to do so, subject to the following - * conditions: - * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES - * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT - * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - * OTHER DEALINGS IN THE SOFTWARE. - */ - -package org.broadinstitute.sting.gatk; - -import java.lang.annotation.*; - -/** - * Allows the walker to be tagged, they can have an unlimited number of categories. - */ -@Documented -@Inherited -@Retention(RetentionPolicy.RUNTIME) -@Target(ElementType.TYPE) -public @interface Categorize { - public Category[] value() default {Category.UNCATEGORIZED}; -} \ No newline at end of file diff --git a/public/java/src/org/broadinstitute/sting/gatk/Category.java b/public/java/src/org/broadinstitute/sting/gatk/Category.java deleted file mode 100644 index d1f890f95..000000000 --- a/public/java/src/org/broadinstitute/sting/gatk/Category.java +++ /dev/null @@ -1,68 +0,0 @@ -/* - * Copyright (c) 2012, The Broad Institute - * - * Permission is hereby granted, free of charge, to any person - * obtaining a copy of this software and associated documentation - * files (the "Software"), to deal in the Software without - * restriction, including without limitation the rights to use, - * copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the - * Software is furnished to do so, subject to the following - * conditions: - * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES - * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT - * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - * OTHER DEALINGS IN THE SOFTWARE. - */ - -package org.broadinstitute.sting.gatk; - -public enum Category { - - BAM_PROCESSING("Walker", "BAM Processing and Analysis Tools"), - - COMPANION("Walker", "Companion Utilities"), - - CANCER_SPECIFIC("Walker", "Cancer-specific Variant Discovery Tools"), - - QUALITY_CONTROL("Walker", "Quality Control and Simple Analysis Tools"), - - VALIDATION("Walker", "Validation Utilities"), - - VARIANT_DETECTION("ex", "Variant Detection"), - - VARIANT_DISCOVERY("Walker", "Variant Discovery Tools"), - - VARIANT_EVALUATION("Walker", "Variant Evaluation and Manipulation Tools"), - - EXPERIMENTAL("Walker", "Miscellaneous Experimental (and Potentially Unstable) Tools"), - - UNCATEGORIZED("all", "No category"); - - private final String description; - - /** - * Accepted strings are from the GATKDocWorkUnit.group - */ - private final String type; - - private Category(String type, String description) { - this.description = description; - this.type = type; - } - - public String type() { - return type; - } - - public String getDescription() { - return description; - } -} diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GATKDocWorkUnit.java b/public/java/src/org/broadinstitute/sting/utils/help/GATKDocWorkUnit.java index 0ff5ddc6a..fd269737f 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDocWorkUnit.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GATKDocWorkUnit.java @@ -25,10 +25,8 @@ package org.broadinstitute.sting.utils.help; import com.sun.javadoc.ClassDoc; -import org.broadinstitute.sting.gatk.Category; import java.util.HashMap; -import java.util.List; import java.util.Map; /** @@ -56,10 +54,6 @@ class GATKDocWorkUnit implements Comparable { * The name of the documentation group (e.g., walkers, read filters) class belongs to */ final String group; - /** - * The categories that this class belongs to - */ - final List categories; /** * The documentation handler for this class */ @@ -81,15 +75,13 @@ class GATKDocWorkUnit implements Comparable { String summary; Map forTemplate; - public GATKDocWorkUnit(String name, String filename, String group, List categories, - DocumentedGATKFeatureObject annotation, DocumentedGATKFeatureHandler handler, - ClassDoc classDoc, Class clazz, + public GATKDocWorkUnit(String name, String filename, String group, DocumentedGATKFeatureObject annotation, + DocumentedGATKFeatureHandler handler, ClassDoc classDoc, Class clazz, String buildTimestamp, String absoluteVersion) { this.annotation = annotation; this.name = name; this.filename = filename; this.group = group; - this.categories = categories; this.handler = handler; this.classDoc = classDoc; this.clazz = clazz; diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java index d4dd47a3a..105e12872 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java @@ -24,7 +24,6 @@ package org.broadinstitute.sting.utils.help; -import com.google.gson.Gson; import com.sun.javadoc.ClassDoc; import com.sun.javadoc.RootDoc; import freemarker.template.Configuration; @@ -35,8 +34,6 @@ import org.apache.commons.io.FileUtils; import org.apache.log4j.Level; import org.apache.log4j.Logger; import org.broad.tribble.FeatureCodec; -import org.broadinstitute.sting.gatk.Categorize; -import org.broadinstitute.sting.gatk.Category; import org.broadinstitute.sting.gatk.CommandLineGATK; import org.broadinstitute.sting.gatk.walkers.qc.DocumentationTest; import org.broadinstitute.sting.utils.exceptions.ReviewedStingException; @@ -44,16 +41,15 @@ import org.broadinstitute.sting.utils.exceptions.UserException; import org.broadinstitute.sting.utils.text.XReadLines; import java.io.*; -import java.lang.annotation.Annotation; import java.util.*; /** * Javadoc Doclet that combines javadoc, GATK ParsingEngine annotations, and FreeMarker * templates to produce html formatted GATKDocs for walkers * and other classes. - * + *

* This document has the following workflow: - * + *

* 1 -- walk the javadoc heirarchy, looking for class that have the * DocumentedGATKFeature annotation or are in the type heirarchy in the * static list of things to document, and are to be documented @@ -63,7 +59,7 @@ import java.util.*; * as well as links to related features via their units. Writing * of a specific class HTML is accomplished by a generate DocumentationHandler * 4 -- write out an index of all units, organized by group - * + *

* The documented classes are restricted to only those with @DocumentedGATKFeature * annotation or are in the STATIC_DOCS class. */ @@ -207,12 +203,19 @@ public class GATKDoclet { myWorkUnits = computeWorkUnits(); - Map>> catNav = getCategories(new ArrayList(myWorkUnits)); - - processCategories(catNav, myWorkUnits); + List> groups = new ArrayList>(); + Set seenDocumentationFeatures = new HashSet(); + List> data = new ArrayList>(); + for (GATKDocWorkUnit workUnit : myWorkUnits) { + data.add(workUnit.indexDataMap()); + if (!seenDocumentationFeatures.contains(workUnit.annotation.groupName())) { + groups.add(toMap(workUnit.annotation)); + seenDocumentationFeatures.add(workUnit.annotation.groupName()); + } + } for (GATKDocWorkUnit workUnit : myWorkUnits) { - processDocWorkUnit(cfg, workUnit, catNav); + processDocWorkUnit(cfg, workUnit, groups, data); } processIndex(cfg, new ArrayList(myWorkUnits)); @@ -257,43 +260,6 @@ public class GATKDoclet { } } - private void processCategories(Map>> getCategories, Set classes) throws IOException { - List categories = new LinkedList(); - for (Category cat : getCategories.keySet()) { - Map properties = new HashMap(); - properties.put("Name", cat.getDescription()); - properties.put("UrlSlug", cat.name().toLowerCase().replace('_', '-')); - categories.add(properties); - } - writeJson(DESTINATION_DIR + "/categories.json", categories); - - List posts = new LinkedList(); - for (GATKDocWorkUnit unit : classes) { - Map properties = new HashMap(); - properties.put("Post Title", unit.name + " Documentation"); - properties.put("Categories", unit.categories); - List tags = new ArrayList(); - tags.add(unit.name); - tags.add(unit.group); - properties.put("Tags", tags); - String body = String.format("%s

%s

", - GATKDocUtils.URL_ROOT_FOR_RELEASE_GATKDOCS + unit.filename, unit.name + " Documentation", unit.summary); - properties.put("Body", body); - posts.add(properties); - } - - } - - private void writeJson(String filename, Object source) throws IOException { - Gson gson = new Gson(); - BufferedWriter out = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(new File(filename))), 1024 * 1024); - - out.write(gson.toJson(source)); - - out.close(); - - } - /** * Returns the set of all GATKDocWorkUnits that we are going to generate docs for. * @@ -318,10 +284,8 @@ public class GATKDoclet { if (handler != null && handler.includeInDocs(doc)) { logger.info("Generating documentation for class " + doc); String filename = handler.getDestinationFilename(doc, clazz); - Category[] categories = getClassAnnotationValue(clazz, Categorize.class, "value"); GATKDocWorkUnit unit = new GATKDocWorkUnit(doc.name(), - filename, feature.groupName(), (categories == null) ? new ArrayList() : Arrays.asList(categories), - feature, handler, doc, clazz, + filename, feature.groupName(), feature, handler, doc, clazz, buildTimestamp, absoluteVersion); m.add(unit); } @@ -451,8 +415,6 @@ public class GATKDoclet { root.put("timestamp", buildTimestamp); root.put("version", absoluteVersion); - root.put("categories", getCategories(indexData)); - return root; } @@ -498,14 +460,16 @@ public class GATKDoclet { * * @param cfg * @param unit + * @param data * @throws IOException */ - private void processDocWorkUnit(Configuration cfg, GATKDocWorkUnit unit, Map>> categories) + private void processDocWorkUnit(Configuration cfg, GATKDocWorkUnit unit, List> groups, List> data) throws IOException { //System.out.printf("Processing documentation for class %s%n", unit.classDoc); unit.handler.processOne(unit); - unit.forTemplate.put("catNav", categories); + unit.forTemplate.put("groups", groups); + unit.forTemplate.put("data", data); // Get or create a template Template temp = cfg.getTemplate(unit.handler.getTemplateName(unit.classDoc)); @@ -520,45 +484,6 @@ public class GATKDoclet { } } - // hack - todo - is there a better way to process annotations? - private Category[] getClassAnnotationValue(Class classType, Class annotationType, String attributeName) { - Category[] value = null; - - Annotation annotation = classType.getAnnotation(annotationType); - if (annotation != null) { - try { - value = (Category[]) annotation.annotationType().getMethod(attributeName).invoke(annotation); - } catch (Exception ex) { - } - } - - return value; - } - - private Map>> getCategories(List classes) { - Map>> output = new TreeMap>>(); - - for (Category cat : Category.values()) { - output.put(cat, new ArrayList>()); - } - - for (GATKDocWorkUnit unit : classes) { - Category[] categories = getClassAnnotationValue(unit.clazz, Categorize.class, "value"); - - if (categories != null) { - for (Category cat : categories) { - unit.handler.processOne(unit); - - Map datum = unit.indexDataMap(); - - output.get(cat).add(datum); - } - } - } - - return output; - } - private static String getSimpleVersion(String absoluteVersion) { String[] parts = absoluteVersion.split("-"); diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java index 71c82053f..69d2e7c9e 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java @@ -88,6 +88,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { addHighLevelBindings(root); addArgumentBindings(root); addRelatedBindings(root); + root.put("group", toProcess.group); toProcess.setHandlerContent((String) root.get("summary"), root); } @@ -109,7 +110,6 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { root.put("description", toProcess.classDoc.commentText().substring(summaryBuilder.toString().length())); root.put("timestamp", toProcess.buildTimestamp); root.put("version", toProcess.absoluteVersion); - root.put("categories", toProcess.categories); for (Tag tag : toProcess.classDoc.tags()) { root.put(tag.name(), tag.text()); diff --git a/settings/helpTemplates/common.html b/settings/helpTemplates/common.html index 4561f6576..45148bda6 100644 --- a/settings/helpTemplates/common.html +++ b/settings/helpTemplates/common.html @@ -28,7 +28,7 @@ --> - <#global siteRoot = "http://gsa-stage:8080/" /> + <#global siteRoot = "http://www.broadinstitute.org/gatk/" /> <#global forum = "http://gatk.vanillaforums.com/" /> <#macro makeHeader title isIndex> @@ -49,9 +49,9 @@ body { padding-top : 60px; } + } -
@@ -63,7 +63,7 @@
- <#macro getCategories map filter> + <#macro getCategories groups> -