rife2/bld-dokka
rife2/bld-dokka
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Ensured exit status is set on failure
Some checks failed
bld-ci / build-bld-project (17, 1.19.24) (push) Has been cancelled
Details
bld-ci / build-bld-project (17, 2.0.0) (push) Has been cancelled
Details
bld-ci / build-bld-project (21, 1.19.24) (push) Has been cancelled
Details
bld-ci / build-bld-project (21, 2.0.0) (push) Has been cancelled
Details
bld-ci / build-bld-project (22, 1.19.24) (push) Has been cancelled
Details
bld-ci / build-bld-project (22, 2.0.0) (push) Has been cancelled
Details
javadocs-pages / deploy (push) Has been cancelled
Details

Browse source
This commit is contained in:
Erik C. Thauvin 2024-07-22 10:23:19 -07:00
parent bd9aa20223
commit 6a6d6ce62a
Signed by: erik
GPG key ID: 776702A6A2DA330E
5 changed files with 175 additions and 115 deletions
Download patch file Download diff file Expand all files Collapse all files

1
examples/.idea/misc.xml generated
View file

@ -6,6 +6,7 @@
<pattern value="com.example.ExampleBuild" method="dokkaHtml" />
<pattern value="com.example.ExampleBuild" method="dokkaGfm" />
<pattern value="com.example.ExampleBuild" method="dokkaJekyll" />
<pattern value="com.example.ExampleBuild" method="docs" />
</component>
<component name="PDMPlugin">
<option name="customRuleSets">

2
examples/README.md
View file

@ -20,6 +20,8 @@
## Build the documentation with [Dokka](https://github.com/Kotlin/dokka)
```console
./bld docs
./bld javadoc
./bld dokka-html
./bld dokka-gfm

8
examples/src/bld/java/com/example/ExampleBuild.java
View file

@ -68,6 +68,14 @@ public class ExampleBuild extends Project {
.execute();
}
@BuildCommand(value = "docs", summary = "Generates all documentation")
public void docs() throws ExitStatusException, IOException, InterruptedException {
dokkaGfm();
dokkaHtml();
dokkaJekyll();
javadoc();
}
@BuildCommand(value = "dokka-gfm", summary = "Generates documentation in GitHub flavored markdown format")
public void dokkaGfm() throws ExitStatusException, IOException, InterruptedException {
new DokkaOperation()

234
src/main/java/rife/bld/extension/DokkaOperation.java
View file

@ -21,9 +21,11 @@ import rife.bld.extension.dokka.LoggingLevel;
import rife.bld.extension.dokka.OutputFormat;
import rife.bld.extension.dokka.SourceSet;
import rife.bld.operations.AbstractProcessOperation;
import rife.bld.operations.exceptions.ExitStatusException;
import rife.tools.StringUtils;
import java.io.File;
import java.io.IOException;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.logging.Level;
@ -78,6 +80,8 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
/**
* Returns the JARs contained in a given directory.
* <p>
* Sources and Javadoc JARs are ignored.
*
* @param directory the directory
* @param regex the regular expression to match
@ -124,6 +128,18 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
return this;
}
@Override
public void execute() throws IOException, InterruptedException, ExitStatusException {
if (project_ == null) {
if (LOGGER.isLoggable(Level.SEVERE) && !silent()) {
LOGGER.severe("A project must be specified.");
}
throw new ExitStatusException(ExitStatusException.EXIT_FAILURE);
} else {
super.execute();
}
}
/**
* Part of the {@link #execute execute} operation, constructs the command list to use for building the process.
*
@ -131,136 +147,134 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
*/
@Override
protected List<String> executeConstructProcessCommandList() {
if (project_ == null) {
throw new IllegalArgumentException("A project must be specified.");
}
final List<String> args = new ArrayList<>();
// java
args.add(javaTool());
if (project_ != null) {
// java
args.add(javaTool());
var cli = getJarList(project_.libBldDirectory(), "^.*dokka-cli.*\\.jar$");
if (cli.size() != 1) {
throw new RuntimeException("The dokka-cli JAR could not be found.");
}
// -jar dokka-cli
args.add("-jar");
args.add(cli.get(0).getAbsolutePath());
// -pluginClasspath
if (!pluginsClasspath_.isEmpty()) {
args.add("-pluginsClasspath");
args.add(pluginsClasspath_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
}
// -sourceSet
var sourceSetArgs = sourceSet_.args();
if (sourceSetArgs.isEmpty()) {
throw new IllegalArgumentException("At least one sourceSet is required.");
} else {
args.add("-sourceSet");
args.add(String.join(" ", sourceSet_.args()));
}
// -outputDir
if (outputDir_ != null) {
if (!outputDir_.exists() && !outputDir_.mkdirs()) {
throw new RuntimeException("Could not create: " + outputDir_.getAbsolutePath());
var jarList = getJarList(project_.libBldDirectory(), "^.*dokka-cli.*\\.jar$");
if (!jarList.isEmpty()) {
// class path
args.add("-cp");
args.add(jarList.stream().map(File::getAbsolutePath).collect(Collectors.joining(File.pathSeparator)));
}
args.add("-outputDir");
args.add(outputDir_.getAbsolutePath());
}
// main class
args.add("org.jetbrains.dokka.MainKt");
// -delayTemplateSubstitution
if (delayTemplateSubstitution_) {
args.add("-delayTemplateSubstitution");
}
// -pluginClasspath
if (!pluginsClasspath_.isEmpty()) {
args.add("-pluginsClasspath");
args.add(pluginsClasspath_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
}
// -failOnWarning
if (failOnWarning_) {
args.add("-failOnWarning");
}
// -sourceSet
var sourceSetArgs = sourceSet_.args();
if (sourceSetArgs.isEmpty()) {
throw new IllegalArgumentException("At least one sourceSet is required.");
} else {
args.add("-sourceSet");
args.add(String.join(" ", sourceSet_.args()));
}
// -globalLinks_
if (!globalLinks_.isEmpty()) {
args.add("-globalLinks");
var links = new ArrayList<String>();
globalLinks_.forEach((k, v) ->
links.add(String.format("%s^%s", k, v)));
args.add(String.join("^^", links));
}
// -outputDir
if (outputDir_ != null) {
if (!outputDir_.exists() && !outputDir_.mkdirs()) {
throw new RuntimeException("Could not create: " + outputDir_.getAbsolutePath());
}
// -globalPackageOptions
if (!globalPackageOptions_.isEmpty()) {
args.add("-globalPackageOptions");
args.add(String.join(SEMICOLON, globalPackageOptions_));
}
args.add("-outputDir");
args.add(outputDir_.getAbsolutePath());
}
// -globalSrcLinks
if (!globalSrcLinks_.isEmpty()) {
args.add("-globalSrcLinks_");
args.add(String.join(SEMICOLON, globalSrcLinks_));
}
// -delayTemplateSubstitution
if (delayTemplateSubstitution_) {
args.add("-delayTemplateSubstitution");
}
// -includes
if (!includes_.isEmpty()) {
args.add("-includes");
args.add(includes_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
}
// -failOnWarning
if (failOnWarning_) {
args.add("-failOnWarning");
}
// -loggingLevel
if (loggingLevel_ != null) {
args.add("-loggingLevel");
args.add(loggingLevel_.name().toLowerCase());
}
// -globalLinks_
if (!globalLinks_.isEmpty()) {
args.add("-globalLinks");
var links = new ArrayList<String>();
globalLinks_.forEach((k, v) ->
links.add(String.format("%s^%s", k, v)));
args.add(String.join("^^", links));
}
// -moduleName
if (isNotBlank(moduleName_)) {
args.add("-moduleName");
args.add(moduleName_);
}
// -globalPackageOptions
if (!globalPackageOptions_.isEmpty()) {
args.add("-globalPackageOptions");
args.add(String.join(SEMICOLON, globalPackageOptions_));
}
// -moduleVersion
if (isNotBlank(moduleVersion_)) {
args.add("-moduleVersion");
args.add(moduleVersion_);
}
// -globalSrcLinks
if (!globalSrcLinks_.isEmpty()) {
args.add("-globalSrcLinks_");
args.add(String.join(SEMICOLON, globalSrcLinks_));
}
// -noSuppressObviousFunctions
if (noSuppressObviousFunctions_) {
args.add("-noSuppressObviousFunctions");
}
// -includes
if (!includes_.isEmpty()) {
args.add("-includes");
args.add(includes_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
}
// -offlineMode
if (offlineMode_) {
args.add("-offlineMode");
}
// -loggingLevel
if (loggingLevel_ != null) {
args.add("-loggingLevel");
args.add(loggingLevel_.name().toLowerCase());
}
// -pluginConfiguration
if (!pluginsConfiguration_.isEmpty()) {
args.add("-pluginsConfiguration");
var confs = new ArrayList<String>();
pluginsConfiguration_.forEach((k, v) ->
confs.add(String.format("%s=%s", encodeJson(k), encodeJson(v))));
args.add(String.join("^^", confs));
}
// -moduleName
if (isNotBlank(moduleName_)) {
args.add("-moduleName");
args.add(moduleName_);
}
// -suppressInheritedMembers
if (suppressInheritedMembers_) {
args.add("-suppressInheritedMembers");
}
// -moduleVersion
if (isNotBlank(moduleVersion_)) {
args.add("-moduleVersion");
args.add(moduleVersion_);
}
// json
if (json_ != null) {
args.add(json_.getAbsolutePath());
}
// -noSuppressObviousFunctions
if (noSuppressObviousFunctions_) {
args.add("-noSuppressObviousFunctions");
}
if (LOGGER.isLoggable(Level.FINE)) {
LOGGER.fine(String.join(" ", args));
// -offlineMode
if (offlineMode_) {
args.add("-offlineMode");
}
// -pluginConfiguration
if (!pluginsConfiguration_.isEmpty()) {
args.add("-pluginsConfiguration");
var confs = new ArrayList<String>();
pluginsConfiguration_.forEach((k, v) ->
confs.add(String.format("%s=%s", encodeJson(k), encodeJson(v))));
args.add(String.join("^^", confs));
}
// -suppressInheritedMembers
if (suppressInheritedMembers_) {
args.add("-suppressInheritedMembers");
}
// json
if (json_ != null) {
args.add(json_.getAbsolutePath());
}
if (LOGGER.isLoggable(Level.FINE)) {
LOGGER.fine(String.join(" ", args));
}
}
return args;

45
src/test/java/rife/bld/extension/DokkaOperationTest.java
View file

@ -16,11 +16,13 @@
package rife.bld.extension;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import rife.bld.blueprints.BaseProjectBlueprint;
import rife.bld.extension.dokka.LoggingLevel;
import rife.bld.extension.dokka.OutputFormat;
import rife.bld.extension.dokka.SourceSet;
import rife.bld.operations.exceptions.ExitStatusException;
import java.io.File;
import java.io.IOException;
@ -29,11 +31,17 @@ import java.nio.file.Paths;
import java.util.Arrays;
import java.util.List;
import java.util.Map;
import java.util.logging.ConsoleHandler;
import java.util.logging.Level;
import java.util.logging.Logger;
import java.util.stream.IntStream;
import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.assertj.core.api.AssertionsForClassTypes.assertThatCode;
class DokkaOperationTest {
private static final File EXAMPLES = new File("examples");
private static final String FILE_1 = "file1";
private static final String FILE_2 = "file2";
private static final String FILE_3 = "file3";
@ -47,18 +55,28 @@ class DokkaOperationTest {
private static final String PATH_3 = "path3";
private static final String PATH_4 = "path4";
@BeforeAll
static void beforeAll() {
var level = Level.ALL;
var logger = Logger.getLogger("rife.bld.extension");
var consoleHandler = new ConsoleHandler();
consoleHandler.setLevel(level);
logger.addHandler(consoleHandler);
logger.setLevel(level);
logger.setUseParentHandlers(false);
}
@Test
void executeConstructProcessCommandListTest() throws IOException {
var args = Files.readAllLines(Paths.get("src", "test", "resources", "dokka-args.txt"));
assertThat(args).isNotEmpty();
var examples = new File("examples");
var jsonConf = new File("config.json");
var op = new DokkaOperation()
.delayTemplateSubstitution(true)
.failOnWarning(true)
.fromProject(new BaseProjectBlueprint(examples, "com.example", "Example"))
.fromProject(new BaseProjectBlueprint(EXAMPLES, "com.example", "Example"))
.globalLinks("s", "gLink1")
.globalLinks(Map.of("s2", "gLink2"))
.globalPackageOptions(OPTION_1, OPTION_2)
@ -74,7 +92,7 @@ class DokkaOperationTest {
.moduleVersion("1.0")
.noSuppressObviousFunctions(true)
.offlineMode(true)
.outputDir(new File(examples, "build"))
.outputDir(new File(EXAMPLES, "build"))
.outputFormat(OutputFormat.JAVADOC)
.pluginConfigurations("name", "{\"json\"}")
.pluginConfigurations(Map.of("{\"name2\"}", "json2", "name3}", "{json3"))
@ -107,10 +125,11 @@ class DokkaOperationTest {
assertThat(found).as(p + " not found.").isTrue();
}
var path = examples.getAbsolutePath();
var path = EXAMPLES.getAbsolutePath();
var dokkaJar = "1.9.20.jar";
var matches = List.of("java",
"-jar", path + "/lib/bld/dokka-cli-" + dokkaJar,
"-cp", path + "/lib/bld/dokka-cli-" + dokkaJar,
"org.jetbrains.dokka.MainKt",
"-pluginsClasspath", path + "/lib/bld/dokka-base-" + dokkaJar + ';' +
path + "/lib/bld/analysis-kotlin-descriptors-" + dokkaJar + ';' +
path + "/lib/bld/javadoc-plugin-" + dokkaJar + ';' +
@ -146,4 +165,20 @@ class DokkaOperationTest {
}
});
}
@Test
void executeNoProjectTest() {
var op = new DokkaOperation();
assertThatThrownBy(op::execute).isInstanceOf(ExitStatusException.class);
}
@Test
void executeTest() {
var op = new DokkaOperation()
.fromProject(
new BaseProjectBlueprint(EXAMPLES, "com.example", "examples"))
.outputDir("build/javadoc")
.outputFormat(OutputFormat.JAVADOC);
assertThatCode(op::execute).doesNotThrowAnyException();
}
}