From 00fdda3214a13e5bc9e6ec423479e427284c2f7f Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Fri, 19 Apr 2024 02:38:36 -0600 Subject: [PATCH] resolves #44 rename the playbook parameter and property to playbookFile and antora.playbookFile, respectively; map playbook as alias --- CHANGELOG.adoc | 6 +++++ docs/modules/ROOT/pages/antora-goal.adoc | 25 ++++++++++--------- src/it/help/verify.groovy | 2 +- src/it/src-main-antora/pom.xml | 2 +- .../org/antora/maven/AntoraMavenPlugin.java | 20 +++++++-------- 5 files changed, 31 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index ea33f87..ec05cfb 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -5,6 +5,12 @@ For a detailed view of what's changed, refer to the repository https://gitlab.co This project utilizes semantic versioning. +== Unreleased + +=== Changed + +* Rename the `playbook` parameter and property to `playbookFile` and `antora.playbookFile`, respectively; map `playbook` as alias (#44) + == 1.0.0-alpha.3 (2024-04-17) === Added diff --git a/docs/modules/ROOT/pages/antora-goal.adoc b/docs/modules/ROOT/pages/antora-goal.adoc index 84f2f06..de6b859 100644 --- a/docs/modules/ROOT/pages/antora-goal.adoc +++ b/docs/modules/ROOT/pages/antora-goal.adoc @@ -260,8 +260,8 @@ Type:: List Required:: false User property:: antora.additionalOptions -[#playbook] -=== +[#playbookFile] +=== The Antora playbook file to use. The value can be an absolute or relative path. @@ -271,15 +271,16 @@ If the path is relative, it's resolved from the directory of the current Maven p [,xml] ---- - src/main/antora/antora-playbook.yml + src/main/antora/antora-playbook.yml ---- [.properties] Type:: File Required:: true +Alias:: playbook Default:: antora-playbook.yml -User property:: antora.playbook +User property:: antora.playbookFile [#playbookProvider] === @@ -461,13 +462,13 @@ Consider the following scenario: [,xml] ---- - antora-playbook.yml + antora-playbook.yml ---- -Now let's say you want to override the `playbook` property using its user property (`antora.playbook`) when calling Maven: +Now let's say you want to override the `playbookFile` property using its user property (`antora.playbookFile`) when calling Maven: - $ mvn antora:antora -Dantora.playbook=author-antora-playbook.yml + $ mvn antora:antora -Dantora.playbookFile=author-antora-playbook.yml In this case, the user property is ignored. That's because the parameter has already been defined in the POM, which has higher precedence. @@ -483,16 +484,16 @@ For example: [,xml] ---- - antora-playbook.yml + antora-playbook.yml ---- -Then, in the plugin configuration, reference this user property when assigning a value to the `playbook` parameter. +Then, in the plugin configuration, reference this user property when assigning a value to the `playbookFile` parameter. [,xml] ---- - ${antora.playbook} + ${antora.playbookFile} ---- @@ -500,9 +501,9 @@ NOTE: When using the user property name for the parameter, this step is not actu Now, you can override the parameter value using the user property: - $ mvn antora:antora -Dantora.playbook=author-antora-playbook.yml + $ mvn antora:antora -Dantora.playbookFile=author-antora-playbook.yml -If you want, you can use a custom property name (e.g., `user.antora.playbook`) for this technique instead of using the same one mapped to the parameter. +If you want, you can use a custom property name (e.g., `user.antora.playbookFile`) for this technique instead of using the same one mapped to the parameter. This technique will only work when using basic parameters (i.e., parameters that are defined using a String value). But that's why the goal offers the `additionalOptions` and `additionalPackages` parameters as an alternative. diff --git a/src/it/help/verify.groovy b/src/it/help/verify.groovy index 7a12e13..e801d18 100644 --- a/src/it/help/verify.groovy +++ b/src/it/help/verify.groovy @@ -1,4 +1,4 @@ String stdout = new File(basedir, "build.log").text assert stdout.contains("A Maven plugin that runs Antora on your project.") assert stdout.contains("This plugin has 2 goals:") -assert stdout.contains("playbook (Default: antora-playbook.yml)") +assert stdout.contains("playbookFile (Default: antora-playbook.yml)") diff --git a/src/it/src-main-antora/pom.xml b/src/it/src-main-antora/pom.xml index 91ee6bc..0b6c5c7 100644 --- a/src/it/src-main-antora/pom.xml +++ b/src/it/src-main-antora/pom.xml @@ -12,7 +12,7 @@ @project.artifactId@ @project.version@ - src/main/antora/antora-playbook.yml + src/main/antora/antora-playbook.yml diff --git a/src/main/java/org/antora/maven/AntoraMavenPlugin.java b/src/main/java/org/antora/maven/AntoraMavenPlugin.java index 919b9ec..2dcd679 100644 --- a/src/main/java/org/antora/maven/AntoraMavenPlugin.java +++ b/src/main/java/org/antora/maven/AntoraMavenPlugin.java @@ -39,9 +39,9 @@ public class AntoraMavenPlugin extends AbstractMojo { private static final String ANTORA_OPTION_PREFIX = "antora.option."; - private static final String DEFAULT_ANTORA_PLAYBOOK = "antora-playbook.yml"; + private static final String DEFAULT_PLAYBOOK_FILE = "antora-playbook.yml"; - private static final String PROVIDED_ANTORA_PLAYBOOK = "provided-antora-playbook.yml"; + private static final String PROVIDED_PLAYBOOK_FILE = "provided-antora-playbook.yml"; private static final String NODE_MODULES = "node_modules"; @@ -136,8 +136,8 @@ public class AntoraMavenPlugin extends AbstractMojo { /** * Sets the Antora playbook file to pass to Antora. */ - @Parameter(defaultValue = DEFAULT_ANTORA_PLAYBOOK, property = "antora.playbook", required = true) - private File playbook; + @Parameter(alias = "playbook", defaultValue = DEFAULT_PLAYBOOK_FILE, property = "antora.playbook", required = true) + private File playbookFile; /** * Sets the location of a playbook template to sideload or download to provided-antora-playbook.yml to use as the @@ -187,7 +187,7 @@ public class AntoraMavenPlugin extends AbstractMojo { String playbookArgument; boolean usingNodeModules = false; if (this.playbookProvider == null) { - playbookArgument = basedir.toPath().relativize(this.playbook.toPath()).toString(); + playbookArgument = basedir.toPath().relativize(this.playbookFile.toPath()).toString(); PackageJsonExplorer packageJsonExplorer = new PackageJsonExplorer(basedir); if (packageJsonExplorer.hasPackageFileWithDependencies()) { usingNodeModules = true; @@ -211,7 +211,7 @@ public class AntoraMavenPlugin extends AbstractMojo { addPackages(this.additionalPackages, allPackages); } } else { - File providedPlaybook = new File(basedir, PROVIDED_ANTORA_PLAYBOOK); + File providedPlaybook = new File(basedir, PROVIDED_PLAYBOOK_FILE); playbookArgument = providedPlaybook.getName(); Map providedPackages = new ProvidedPlaybookRetriever(getLog(), basedir) .retrievePlaybook(this.playbookProvider, providedPlaybook); @@ -242,8 +242,8 @@ public class AntoraMavenPlugin extends AbstractMojo { ", which is not compatible with this plugin. Please delete it."); } this.playbookProvider = PlaybookProvider.validate(this.playbookProvider); - if (this.playbookProvider == null && !this.playbook.exists()) { - String message = "Antora playbook file not found: " + this.playbook; + if (this.playbookProvider == null && !this.playbookFile.exists()) { + String message = "Antora playbook file not found: " + this.playbookFile; getLog().error("Cannot run Antora because " + message); throw new MojoExecutionException(message); } @@ -259,7 +259,7 @@ public class AntoraMavenPlugin extends AbstractMojo { return env; } - private String npxAntoraArguments(Collection allPackages, List allOptions, String playbook) { + private String npxAntoraArguments(Collection allPackages, List allOptions, String argument) { List arguments = new ArrayList<>(List.of("--yes")); if (allPackages.isEmpty()) { arguments.set(0, "--offline"); @@ -270,7 +270,7 @@ public class AntoraMavenPlugin extends AbstractMojo { } arguments.add(ANTORA_COMMAND_NAME); arguments.addAll(antoraOptions(allOptions)); - arguments.add(playbook); + arguments.add(argument); return String.join(" ", arguments); } -- GitLab