Repository: karaf Updated Branches: refs/heads/master 33b23afe1 -> b318e0002
KARAF-4240 - Add asciidoc command help printer Project: http://git-wip-us.apache.org/repos/asf/karaf/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf/commit/b318e000 Tree: http://git-wip-us.apache.org/repos/asf/karaf/tree/b318e000 Diff: http://git-wip-us.apache.org/repos/asf/karaf/diff/b318e000 Branch: refs/heads/master Commit: b318e0002e4833bf352fcd741c944fb90f4a4ffc Parents: 33b23af Author: Jean-Baptiste Onofré <[email protected]> Authored: Tue Dec 29 08:03:08 2015 +0100 Committer: Jean-Baptiste Onofré <[email protected]> Committed: Tue Dec 29 08:03:08 2015 +0100 ---------------------------------------------------------------------- .../commands/AsciiDoctorCommandHelpPrinter.java | 149 +++++++++++++++++++ .../tooling/commands/CommandHelpPrinter.java | 2 + .../commands/DocBookCommandHelpPrinter.java | 1 - .../tooling/commands/GenerateHelpMojo.java | 43 ++++-- .../commands/UserConfCommandHelpPrinter.java | 1 - 5 files changed, 185 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf/blob/b318e000/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java new file mode 100644 index 0000000..0e292b5 --- /dev/null +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/AsciiDoctorCommandHelpPrinter.java @@ -0,0 +1,149 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.karaf.tooling.commands; + +import org.apache.karaf.shell.api.action.Action; +import org.apache.karaf.shell.api.action.Argument; +import org.apache.karaf.shell.api.action.Command; +import org.apache.karaf.shell.api.action.Option; +import org.apache.karaf.shell.impl.action.command.HelpOption; + +import java.io.PrintStream; +import java.lang.reflect.Field; +import java.util.*; + +/** + * Prints documentation in asciidoc syntax + */ +public class AsciiDoctorCommandHelpPrinter extends AbstractCommandHelpPrinter { + + @Override + public void printHelp(Action action, PrintStream out, boolean includeHelpOption) { + Command command = action.getClass().getAnnotation(Command.class); + Set<Option> options = new HashSet<>(); + List<Argument> arguments = new ArrayList<Argument>(); + Map<Argument, Field> argFields = new HashMap<>(); + Map<Option, Field> optFields = new HashMap<>(); + for (Class<?> type = action.getClass(); type != null; type = type.getSuperclass()) { + for (Field field : type.getDeclaredFields()) { + Option option = field.getAnnotation(Option.class); + if (option != null) { + options.add(option); + } + + Argument argument = field.getAnnotation(Argument.class); + if (argument != null) { + argument = replaceDefaultArgument(field, argument); + argFields.put(argument, field); + int index = argument.index(); + while (arguments.size() <= index) { + arguments.add(null); + } + if (arguments.get(index) != null) { + throw new IllegalArgumentException("Duplicate argument index: " + index + " on Action " + action.getClass().getName()); + } + arguments.set(index, argument); + } + } + } + if (includeHelpOption) + options.add(HelpOption.HELP); + + out.println("= " + command.scope() + ":" + command.name()); + out.println(); + + out.println("== Description"); + out.println(command.description()); + out.println(); + + StringBuffer syntax = new StringBuffer(); + syntax.append(String.format("%s:%s", command.scope(), command.name())); + if (options.size() > 0) { + syntax.append(" [options]"); + } + if (arguments.size() > 0) { + syntax.append(' '); + for (Argument argument : arguments) { + syntax.append(String.format(argument.required() ? "%s " : "[%s] ", argument.name())); + } + } + out.println("== Syntax"); + out.println(syntax.toString()); + out.println(); + + if (arguments.size() > 0) { + out.println("== Arguments"); + out.println("|==="); + out.println("|Name |Description"); + for (Argument argument : arguments) { + String description = argument.description(); + if (!argument.required()) { + Object o = getDefaultValue(action, argFields.get(argument)); + String defaultValue = getDefaultValueString(o); + if (defaultValue != null) { + description += " (defaults to " + o.toString() + ")"; + } + } + out.println("| " + argument.name()); + out.println("| " + description); + } + out.println("|==="); + } + if (options.size() > 0) { + out.println("== Options"); + out.println("|==="); + out.println("|Name |Description"); + for (Option option : options) { + String opt = option.name(); + String desc = option.description(); + for (String alias : option.aliases()) { + opt += ", " + alias; + } + Object o = getDefaultValue(action, optFields.get(option)); + String defaultValue = getDefaultValueString(o); + if (defaultValue != null) { + desc += " (defaults to " + defaultValue + ")"; + } + out.println("|" + opt); + out.println("|" + desc); + } + out.println("|==="); + } + if (command.detailedDescription().length() > 0) { + out.println("== Details"); + out.println(command.detailedDescription()); + } + out.println(); + } + + @Override + public void printOverview(Map<String, Set<String>> commands, PrintStream writer) { + writer.println("= Commands"); + writer.println(); + for (String key : commands.keySet()) { + writer.println("== " + key); + writer.println(); + for (String cmd : commands.get(key)) { + writer.println("* [" + key + ":" + cmd + "|" + key + "-" + cmd + "]"); + } + writer.println(); + } + } + +} http://git-wip-us.apache.org/repos/asf/karaf/blob/b318e000/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java index f255434..e5915d5 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/CommandHelpPrinter.java @@ -25,6 +25,7 @@ import java.util.Set; import org.apache.karaf.shell.api.action.Action; public interface CommandHelpPrinter { + /** * Print help for a single action to the out stream * @@ -41,4 +42,5 @@ public interface CommandHelpPrinter { * @param out */ void printOverview(Map<String, Set<String>> commands, PrintStream out); + } http://git-wip-us.apache.org/repos/asf/karaf/blob/b318e000/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java index d40841c..7d729b6 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/DocBookCommandHelpPrinter.java @@ -33,7 +33,6 @@ import org.apache.karaf.shell.api.action.Command; import org.apache.karaf.shell.api.action.Option; import org.apache.karaf.shell.impl.action.command.HelpOption; - /** * Prints documentation in docbook syntax */ http://git-wip-us.apache.org/repos/asf/karaf/blob/b318e000/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/GenerateHelpMojo.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/GenerateHelpMojo.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/GenerateHelpMojo.java index 354c1b1..bcf180d 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/GenerateHelpMojo.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/GenerateHelpMojo.java @@ -81,14 +81,14 @@ public class GenerateHelpMojo extends AbstractMojo { @Parameter(defaultValue = "${project}") protected MavenProject project; - private static final String FORMAT_CONF = "conf"; private static final String FORMAT_DOCBX = "docbx"; + private static final String FORMAT_ASCIIDOC = "asciidoc"; public void execute() throws MojoExecutionException, MojoFailureException { try { - if (!FORMAT_DOCBX.equals(format) && !FORMAT_CONF.equals(format)) { - throw new MojoFailureException("Unsupported format: " + format + ". Supported formats are: docbx or conf."); + if (!FORMAT_DOCBX.equals(format) && !FORMAT_CONF.equals(format) && !FORMAT_ASCIIDOC.equals(format)) { + throw new MojoFailureException("Unsupported format: " + format + ". Supported formats are: asciidoc, docbx, or conf."); } if (!targetFolder.exists()) { targetFolder.mkdirs(); @@ -99,14 +99,30 @@ public class GenerateHelpMojo extends AbstractMojo { if (classes.isEmpty()) { throw new MojoFailureException("No command found"); } - - CommandHelpPrinter helpPrinter = FORMAT_DOCBX.equals(format) - ? new DocBookCommandHelpPrinter() - : new UserConfCommandHelpPrinter(); + + CommandHelpPrinter helpPrinter = null; + if (FORMAT_ASCIIDOC.equals(format)) { + helpPrinter = new AsciiDoctorCommandHelpPrinter(); + } + if (FORMAT_CONF.equals(format)) { + helpPrinter = new UserConfCommandHelpPrinter(); + } + if (FORMAT_DOCBX.equals(format)) { + helpPrinter = new DocBookCommandHelpPrinter(); + } Map<String, Set<String>> commands = new TreeMap<String, Set<String>>(); - String commandSuffix = FORMAT_DOCBX.equals(format) ? "xml" : "conf"; + String commandSuffix = null; + if (FORMAT_ASCIIDOC.equals(format)) { + commandSuffix = "adoc"; + } + if (FORMAT_CONF.equals(format)) { + commandSuffix = "conf"; + } + if (FORMAT_DOCBX.equals(format)) { + commandSuffix = "xml"; + } for (Class<?> clazz : classes) { try { Action action = (Action) clazz.newInstance(); @@ -134,7 +150,16 @@ public class GenerateHelpMojo extends AbstractMojo { } } - String overViewSuffix = FORMAT_DOCBX.equals(format) ? "xml" : "conf"; + String overViewSuffix = null; + if (FORMAT_ASCIIDOC.equals(format)) { + overViewSuffix = "adoc"; + } + if (FORMAT_CONF.equals(format)) { + overViewSuffix = "conf"; + } + if (FORMAT_DOCBX.equals(format)) { + overViewSuffix = "xml"; + } PrintStream writer = new PrintStream(new FileOutputStream(new File(targetFolder, "commands." + overViewSuffix))); helpPrinter.printOverview(commands, writer); writer.close(); http://git-wip-us.apache.org/repos/asf/karaf/blob/b318e000/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java ---------------------------------------------------------------------- diff --git a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java index 59f7bd9..669f5b2 100644 --- a/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java +++ b/tooling/karaf-maven-plugin/src/main/java/org/apache/karaf/tooling/commands/UserConfCommandHelpPrinter.java @@ -33,7 +33,6 @@ import org.apache.karaf.shell.api.action.Command; import org.apache.karaf.shell.api.action.Option; import org.apache.karaf.shell.impl.action.command.HelpOption; - /** * Prints documentation in wiki syntax */
