zzh
/
gatk-3.8
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Now links to sub and superclass documentation, where possible.

This commit is contained in:
Mark DePristo 2011-07-24 09:56:17 -04:00
parent 6b501e267b
commit d0ab6bf7a9
4 changed files with 101 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureHandler.java
View File

@ -29,6 +29,7 @@ import com.sun.javadoc.RootDoc;
import java.io.*;
import java.util.Map;
import java.util.Set;
/**
*
@ -51,5 +52,5 @@ public abstract class DocumentedGATKFeatureHandler {
}
public abstract String getTemplateName(ClassDoc doc) throws IOException;
public abstract void processOne(GATKDoclet.DocWorkUnit toProcess, Map<Class, GATKDoclet.DocWorkUnit> all);
public abstract void processOne(GATKDoclet.DocWorkUnit toProcess, Set<GATKDoclet.DocWorkUnit> all);
}

23
public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
View File

@ -102,8 +102,8 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
return ResourceBundleExtractorDoclet.optionLength(option);
}
public Map<Class, DocWorkUnit> workUnits() {
Map<Class, DocWorkUnit> m = new HashMap<Class, DocWorkUnit>();
public Set<DocWorkUnit> workUnits() {
TreeSet<DocWorkUnit> m = new TreeSet<DocWorkUnit>();
for ( ClassDoc doc : rootDoc.classes() ) {
System.out.printf("Considering %s%n", doc);
@ -115,7 +115,7 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
DocWorkUnit unit = new DocWorkUnit(feature,
doc.name(), filename, feature.groupName(),
handler, doc, clazz );
m.put(clazz, unit);
m.add(unit);
}
}
@ -137,12 +137,12 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
// Specify how templates will see the data-model. This is an advanced topic...
cfg.setObjectWrapper(new DefaultObjectWrapper());
Map<Class, DocWorkUnit> workUnitMap = workUnits();
for ( DocWorkUnit workUnit : workUnitMap.values() ) {
processDocWorkUnit(cfg, workUnit, workUnitMap);
Set<DocWorkUnit> myWorkUnits = workUnits();
for ( DocWorkUnit workUnit : myWorkUnits ) {
processDocWorkUnit(cfg, workUnit, myWorkUnits);
}
processIndex(cfg, new ArrayList<DocWorkUnit>(workUnitMap.values()));
processIndex(cfg, new ArrayList<DocWorkUnit>(myWorkUnits));
} catch ( FileNotFoundException e ) {
throw new RuntimeException(e);
} catch ( IOException e ) {
@ -242,7 +242,14 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
return root;
}
private void processDocWorkUnit(Configuration cfg, DocWorkUnit unit, Map<Class, DocWorkUnit> all)
public final static DocWorkUnit findWorkUnitForClass(Class c, Set<DocWorkUnit> all) {
for ( final DocWorkUnit unit : all )
if ( unit.clazz.equals(c) )
return unit;
return null;
}
private void processDocWorkUnit(Configuration cfg, DocWorkUnit unit, Set<DocWorkUnit> all)
throws IOException {
System.out.printf("Processing documentation for class %s%n", unit.classDoc);

62
public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
View File

@ -41,6 +41,10 @@ import java.util.*;
*
*/
public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
GATKDoclet.DocWorkUnit toProcess;
ClassDoc classdoc;
Set<GATKDoclet.DocWorkUnit> all;
@Override
public boolean shouldBeProcessed(ClassDoc doc) {
return true;
@ -59,11 +63,23 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
}
@Override
public void processOne(GATKDoclet.DocWorkUnit toProcess, Map<Class, GATKDoclet.DocWorkUnit> all) {
public void processOne(GATKDoclet.DocWorkUnit toProcessArg, Set<GATKDoclet.DocWorkUnit> allArg) {
this.toProcess = toProcessArg;
this.all = allArg;
this.classdoc = toProcess.classDoc;
System.out.printf("%s class %s%n", toProcess.group, toProcess.classDoc);
ClassDoc classdoc = toProcess.classDoc;
Map<String, Object> root = new HashMap<String, Object>();
addHighLevelBindings(root);
addArgumentBindings(root);
addRelatedBindings(root);
//System.out.printf("Root is %s%n", root);
toProcess.setHandlerContent((String)root.get("summary"), root);
}
protected void addHighLevelBindings(Map<String, Object> root) {
root.put("name", classdoc.name());
// Extract overrides from the doc tags.
@ -76,7 +92,9 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
for(Tag tag: classdoc.tags()) {
root.put(tag.name(), tag.text());
}
}
protected void addArgumentBindings(Map<String, Object> root) {
ParsingEngine parsingEngine = createStandardGATKParsingEngine();
Map<String, List<Object>> args = new HashMap<String, List<Object>>();
@ -102,10 +120,14 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
} catch ( ClassNotFoundException e ) {
throw new RuntimeException(e);
}
}
protected void addRelatedBindings(Map<String, Object> root) {
List<Map<String, Object>> extraDocsData = new ArrayList<Map<String, Object>>();
for ( Class extraDocClass : toProcess.annotation.extraDocs() ) {
final GATKDoclet.DocWorkUnit otherUnit = all.get(extraDocClass);
// add in all of the explicitly related items
for ( final Class extraDocClass : toProcess.annotation.extraDocs() ) {
final GATKDoclet.DocWorkUnit otherUnit = GATKDoclet.findWorkUnitForClass(extraDocClass, all);
if ( otherUnit == null )
throw new ReviewedStingException("Requested extraDocs for class without any documentation: " + extraDocClass);
extraDocsData.add(
@ -114,10 +136,36 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
put("name", otherUnit.name);}});
}
root.put("extradocs", extraDocsData);
//System.out.printf("Root is %s%n", root);
toProcess.setHandlerContent(summaryBuilder.toString(), root);
List<Map<String, Object>> hierarchyDocs = new ArrayList<Map<String, Object>>();
for (final GATKDoclet.DocWorkUnit other : all ) {
final String relation = classRelationship(toProcess.clazz, other.clazz);
if ( relation != null )
hierarchyDocs.add(
new HashMap<String, Object>(){{
put("filename", other.filename);
put("relation", relation);
put("name", other.name);}});
}
root.put("relatedDocs", hierarchyDocs);
root.put("extradocs", extraDocsData);
}
private static final String classRelationship(Class me, Class other) {
if ( other.equals(me) )
// no circular references
return null;
else if ( other.isAssignableFrom(me) )
// toProcess is a superclass of other.clazz
return "superclass";
else if ( me.isAssignableFrom(other) )
// toProcess inherits from other.clazz
return "subclass";
else
return null;
}
protected ParsingEngine createStandardGATKParsingEngine() {

33
settings/helpTemplates/generic.template.html
View File

@ -24,19 +24,36 @@
Details: ${arg.fulltext}<br>
</#macro>
<#macro relatedByType name type>
<#list relatedDocs as relatedDoc>
<#if relatedDoc.relation == type>
<h3>${name}</h3>
<ul>
<#list relatedDocs as relatedDoc>
<#if relatedDoc.relation == type>
<li><a href="${relatedDoc.filename}">${relatedDoc.name}</a> is a ${relatedDoc.relation}</li>
</#if>
</#list>
</ul>
<#break>
</#if>
</#list>
</#macro>
<html>
<head>
<title>${name} documentation</title>
</head>
<body>
<h1>${name}<h1>
<h2>Summary</h2>
<h2>Brief summary</h2>
${summary}
<#if author??>
<h2>Author</h2>
${author}
</#if>
<h2>Description</h2>
<h2>Detailed description</h2>
${description}
<#-- Create the argument summary -->
@ -57,10 +74,10 @@
</table>
</#if>
<#-- Create references to related capabilities if appropriate -->
<#-- Create references to additional capabilities if appropriate -->
<#if extradocs?size != 0>
<hr>
<h2>Related capabilities</h2>
<h2>Additional capabilities</h2>
The arguments described in the entries below can be supplied to this tool to modify
its behavior. For example, the -L argument directs the GATK engine restricts processing
to specific genomic intervals. This capability is available to all GATK walkers.
@ -70,6 +87,14 @@
</#list>
</ul>
</#if>
<#-- This class is related to other documented classes via sub/super relationships -->
<#if relatedDocs?size != 0>
<h2>Related capabilities</h2>
<@relatedByType name="Superclasses" type="superclass"/>
<@relatedByType name="Subclasses" type="subclass"/>
<hr>
</#if>
<#-- List all of the -->
<#if arguments.all?size != 0>