google-nomulus/docs/src/main/java/google/registry/documentation/FlowDocumentationTool.java
Lai Jiang fba8af0485 Migrate the documentation package to Java 11 (#729)
* Migrate the documentation package to Java 11

The old Doclet API is deprected and removed in Java 12. This commit
changes the documentation package to use the new recommended API.
However it is not a drop-in replacement and there are non-idiomatic
usages all over the place. I think it is eaiser to keep the current code
logic and kind of shoehorn in the new API than starting afresh as the
return on investment of a do-over is not great.

Also note that the docs package is disabled as of this commit because we
are still using Java 8 to compile which lacks the new API. Once we
switch our toolchains to Java 11 (but still compiling Java 8 bytecode)
we can re-enable this package.

TESTED=ran `./gradlew :docs:test` locally with the documentation package
enabled.
2020-07-30 17:12:33 -04:00

91 lines
3 KiB
Java

// Copyright 2017 The Nomulus Authors. All Rights Reserved.
//
// Licensed 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 google.registry.documentation;
import static java.nio.charset.StandardCharsets.UTF_8;
import com.beust.jcommander.JCommander;
import com.beust.jcommander.Parameter;
import com.beust.jcommander.ParameterException;
import com.beust.jcommander.Parameters;
import com.google.common.io.Files;
import java.io.File;
import java.io.IOException;
/**
* Tool to generate documentation for the EPP flows and corresponding external API.
*
* <p>Mostly responsible for producing standalone documentation files (HTML and Markdown) from flow
* information objects; those call into javadoc to extract documentation information from the flows
* package source files. See the {@link FlowDocumentation} class for more details.
*/
@Parameters(separators = " =", commandDescription = "Tool to generate EPP API documentation")
public class FlowDocumentationTool {
@Parameter(
names = {"-o", "--output_file"},
description = "file where generated documentation will be written (use '-' for stdout)")
private String outputFileName;
@Parameter(
names = {"--help", "--helpshort"},
description = "print this help",
help = true)
private boolean displayHelp = false;
/** Parses command line flags and then runs the documentation tool. */
public static void main(String[] args) {
FlowDocumentationTool docTool = new FlowDocumentationTool();
JCommander jcommander = new JCommander(docTool);
jcommander.setProgramName("flow_docs_tool");
try {
jcommander.parse(args);
} catch (ParameterException e) {
jcommander.usage();
throw e;
}
if (docTool.displayHelp) {
jcommander.usage();
return;
}
docTool.run();
}
/** Generates flow documentation and then outputs it to the specified file. */
public void run() {
DocumentationGenerator docGenerator;
try {
docGenerator = new DocumentationGenerator();
} catch (Exception e) {
throw new RuntimeException("IO error while running Javadoc tool", e);
}
String output = docGenerator.generateMarkdown();
if (outputFileName.equals("-")) {
System.out.println(output);
} else {
if (outputFileName == null) {
outputFileName = "doclet.md";
}
try {
Files.asCharSink(new File(outputFileName), UTF_8).write(output);
} catch (IOException e) {
throw new RuntimeException("Could not write to specified output file", e);
}
}
}
}