From 6817b4348ff30407257abdf6ad0975846fd4e80d Mon Sep 17 00:00:00 2001 From: Jim Schubert Date: Mon, 15 Oct 2018 03:21:13 -0400 Subject: [PATCH] [cli] config-help writes doc-compat output (#1239) This updates config-help to have more control over how the output is written for the user. We dump config-help output for per-generator documentation, and this cleans up some cross-platform compatibility issues that might arise from tweaking the output for clarity in the target file. Previously, we'd pipe config-help output to sed, then insert the generator name, which we then redirected to an output file. The sed syntax had to include a trailing newline so our tabbed configs would automatically become code tags in markdown. Inserting newlines into sed replacement strings doesn't work the same across platforms, mostly because of Apple's customizations to GNU programs. This commit moves the generator name and newline insertion into the command itself. It also includes a new --output option, allowing the user to specify the output location of the config-help. Currently, we only dump in plain-text, and it is only coincidental that our plaintext output results in a desirable Markdown output. If tabbed lines did not automatically convert to a code style block, some generators like C# would end up with broken text (`List` would become just `List`, for example). I had previously discussed extending config-help to output to other formats like asciidoc. This commit does not introduce any steps toward that end. --- bin/utils/export_docs_generators.sh | 6 +- bin/utils/export_generator.sh | 10 ++-- .../openapitools/codegen/cmd/ConfigHelp.java | 55 ++++++++++++++++--- 3 files changed, 57 insertions(+), 14 deletions(-) diff --git a/bin/utils/export_docs_generators.sh b/bin/utils/export_docs_generators.sh index 80ab491f9aa2..0e1b50998c42 100755 --- a/bin/utils/export_docs_generators.sh +++ b/bin/utils/export_docs_generators.sh @@ -1,11 +1,11 @@ #!/bin/bash SCRIPT="$0" -echo "# START SCRIPT: $SCRIPT" +echo "# START SCRIPT: ${SCRIPT}" executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar" -for GENERATOR in $(java -jar $executable list --short | sed -e 's/,/\'$'\n''/g') +for GENERATOR in $(java -jar ${executable} list --short | sed -e 's/,/\'$'\n''/g') do - ./bin/utils/export_generator.sh $GENERATOR + ./bin/utils/export_generator.sh ${GENERATOR} done diff --git a/bin/utils/export_generator.sh b/bin/utils/export_generator.sh index d9a98f0df544..918ae306eb34 100755 --- a/bin/utils/export_generator.sh +++ b/bin/utils/export_generator.sh @@ -1,17 +1,19 @@ #!/bin/bash SCRIPT="$0" -echo "# START SCRIPT: $SCRIPT" if [[ "$1" != "" ]]; then NAME="$1" + echo "# START SCRIPT: ${SCRIPT} ${NAME}" else - echo "Missing argument. Usage e.g.: ./bin/utils/export-generator.sh jaxrs-jersey" + echo "Missing argument to ${SCRIPT}." + echo " Usage: ${SCRIPT} generator-name" + echo " Example: ${SCRIPT} groovy" exit 1; fi executable="./modules/openapi-generator-cli/target/openapi-generator-cli.jar" -java -jar $executable config-help -g $NAME | sed -e 's/CONFIG OPTIONS/CONFIG OPTIONS for '$NAME'\'$'\n''/g' > docs/generators/$NAME.md +java -jar ${executable} config-help -g ${NAME} --named-header -o docs/generators/${NAME}.md -echo "Back to the [generators list](README.md)" >> docs/generators/$NAME.md +echo "Back to the [generators list](README.md)" >> docs/generators/${NAME}.md diff --git a/modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/ConfigHelp.java b/modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/ConfigHelp.java index b6c4f9b89bcb..4a5cb6bb62d2 100644 --- a/modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/ConfigHelp.java +++ b/modules/openapi-generator-cli/src/main/java/org/openapitools/codegen/cmd/ConfigHelp.java @@ -26,6 +26,9 @@ import org.openapitools.codegen.GeneratorNotFoundException; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import java.io.*; +import java.nio.charset.StandardCharsets; + import static org.apache.commons.lang3.StringUtils.isEmpty; import static org.apache.commons.lang3.StringUtils.isNotEmpty; @@ -42,6 +45,16 @@ public class ConfigHelp implements Runnable { description = "generator to get config help for") private String generatorName; + @Option(name = {"--named-header"}, title = "named header", + description = "Header includes the generator name, for clarity in output") + private Boolean namedHeader; + + @Option(name = {"-o", "--output"}, title = "output location", + description = "Optionally write help to this location, otherwise default is standard output") + private String outputFile; + + private String newline = System.lineSeparator(); + @Override public void run() { @@ -57,19 +70,47 @@ public class ConfigHelp implements Runnable { } try { + StringBuilder sb = new StringBuilder(); CodegenConfig config = CodegenConfigLoader.forName(generatorName); - System.out.println(); - System.out.println("CONFIG OPTIONS"); - for (CliOption langCliOption : config.cliOptions()) { - System.out.println("\t" + langCliOption.getOpt()); - System.out.println("\t " - + langCliOption.getOptionHelp().replaceAll("\n", System.lineSeparator() + "\t ")); - System.out.println(); + + generatePlainTextHelp(sb, config); + + if (!isEmpty(outputFile)) { + File out = new File(outputFile); + //noinspection ResultOfMethodCallIgnored + out.mkdirs(); + + Writer writer = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(out), StandardCharsets.UTF_8)); + + writer.write(sb.toString()); + writer.close(); + } else { + System.out.print(sb.toString()); } } catch (GeneratorNotFoundException e) { System.err.println(e.getMessage()); System.err.println("[error] Check the spelling of the generator's name and try again."); System.exit(1); + } catch (IOException e) { + e.printStackTrace(); + } + } + + private void generatePlainTextHelp(StringBuilder sb, CodegenConfig config) { + sb.append(newline); + sb.append("CONFIG OPTIONS"); + if (Boolean.TRUE.equals(namedHeader)) { + sb.append(" for ").append(generatorName).append(newline); + } + + sb.append(newline); + + for (CliOption langCliOption : config.cliOptions()) { + sb.append("\t").append(langCliOption.getOpt()); + sb.append(newline); + sb.append("\t ").append(langCliOption.getOptionHelp().replaceAll("\n", System.lineSeparator() + "\t ")); + sb.append(newline); + sb.append(newline); } } }