Repository navigation
Generate a reusable Antora documentation list - #389
Conversation
maximthomas
left a comment
There was a problem hiding this comment.
praise: The list is generated where the index already was, and the version handling holds up in a rendered site.
AntoraMojo.createIndexForRootbuilds the partial from<documents>, and the products' deploy workflows (rm -rf <product>/modules, thencp -R …/antora/modules) publish it together with the index.- The
ifevalon{page-component-name}works under Antora 3.1.15. In a rendered two-version site, the ROOT home page links to the latest guides andopendj/4.10/index.htmllinks toreference/index.htmlinside 4.10. Files.exists(listPath)throws aMojoExecutionExceptioninstead of overwriting a source partial, and the new test pins it.
issue (blocking): The antora goal reads the Antora component from a new key, antoraComponentName, but asciidoc-to-pdf already reads the same value from antoraComponent.
commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AntoraMojo.java:45-47, :210-211, commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AsciidocToPdfMojo.java:73-81, :109-110
Both parameters mean the same thing and default to the same value (projectName.toLowerCase(Locale.ROOT)). Products run antora and asciidoc-to-pdf in one execution that shares one configuration (for example OpenAM openam-doc-source/pom.xml). Take a product whose component name differs from its lowercased project name and that sets <antoraComponent>, as the README's PDF example does. Its PDF links come out right. Its index, though, names the default component, and Antora 3.1.15 renders those xrefs unresolved (#dsx:reference:index.adoc); today's index resolves. No product sets either key yet, so nothing breaks now. But such a product would have to configure one value under two keys, and renaming either key after a release breaks existing configurations. Was the separate key deliberate? Even if it was, I'd declare the setting once:
// AbstractAsciidocMojo (needs import java.util.Locale;)
/**
* Antora component of this project on the documentation site, such as {@code openidm}.
*
* <br>
*
* Default: {@code projectName} in lower case.
*/
@Parameter(property = "antoraComponent")
private String antoraComponent;
protected String getAntoraComponent() {
String component = antoraComponent == null ? "" : antoraComponent.trim();
return component.isEmpty() ? projectName.toLowerCase(Locale.ROOT) : component;
}Move the field out of AsciidocToPdfMojo:73-81. Then AsciidocToPdfMojo:109-110 and AntoraMojo:210-211 both become String component = getAntoraComponent();, AntoraMojo:45-47 goes away, and the README section and AntoraMojoTest:84 switch to antoraComponent. Two side effects: every goal that extends AbstractAsciidocMojo gains the parameter, unused, and a whitespace-only -DantoraComponent now falls back to the default in asciidoc-to-pdf as well.
issue (non-blocking): The blank checks trim antoraComponentName and javadocUrl, but the values are written untrimmed.
commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AntoraMojo.java:210, :223-225
With -DantoraComponentName=' opendj', the ifeval compares against " opendj" and never matches, so the product's own pages, older versions included, link to the latest guides. 'opendj ' produces xref:opendj :reference:index.adoc[], and a padded -DjavadocUrl produces link: /opendj/…. Maven trims POM text but not -D values. getAntoraComponent() above trims the component; for the link:
String url = javadocUrl == null ? "" : javadocUrl.trim();
if (!url.isEmpty()) {
builder.append("* link:").append(url).appendln("[API Reference (Javadoc)]");
}No test covers the blank branches, or the Locale.ROOT default for a project name that contains I (OpenIDM, OpenIG).
suggestion (non-blocking): The test checks the generated partial with order-free contains, so the lines that keep product links in their own version are not pinned.
commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AntoraMojoTest.java:76-82
AntoraMojoTest stays green at 8/8 under each of three mutants: deleting the empty-value line :generated-documentation-component: together with the trailing unset, moving the unset before the list, or dropping the blank line before the unset. The first mutant sends every product page, older versions included, to the latest guides. The other two leave literal {generated-documentation-component} hrefs, or leak the attribute into the including page. An exact assertion kills all three:
assertThat(Files.readString(root.resolve("partials/documentation-list.adoc"), StandardCharsets.UTF_8)
.replace("\r\n", "\n"))
.isEqualTo(":generated-documentation-component: opendj:\n"
+ "ifeval::[\"{page-component-name}\" == \"opendj\"]\n"
+ ":generated-documentation-component:\n"
+ "endif::[]\n"
+ "\n"
+ "* xref:{generated-documentation-component}reference:index.adoc[]\n"
+ "* xref:{generated-documentation-component}admin-guide:index.adoc[]\n"
+ "\n"
+ ":generated-documentation-component!:\n");Pin: if you take the leading-blank-line suggestion below, the expected text starts with one more "\n".
suggestion (non-blocking): The new test sets antoraComponentName and javadocUrl by reflection, so their @Parameter wiring is not pinned.
commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AntoraMojoTest.java:84-85
The test POM configures neither parameter, and setVariableValueToObject bypasses the plugin descriptor. Deleting both @Parameter annotations, or renaming their properties, keeps 8/8 green, and a real build would then ignore <javadocUrl> without a warning. The descriptor check that AsciidocToPdfMojoConfigurationTest:80-82 already uses would close this. After the blocking rename, the first key is antoraComponent.
@Test
public void testDocumentationListOptionsAreDescriptorParameters() throws Exception {
Map<String, org.apache.maven.plugin.descriptor.Parameter> parameters =
newMojoExecution("antora").getMojoDescriptor().getParameterMap();
assertEquals("${antoraComponentName}", parameters.get("antoraComponentName").getExpression());
assertEquals("${javadocUrl}", parameters.get("javadocUrl").getExpression());
}Pin: add import java.util.Map;. I checked getExpression() and getParameterMap() against maven-plugin-api 3.9.9 only.
suggestion (non-blocking): The partial starts with an attribute entry, so it is lost when the include sits directly under a paragraph line.
commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AntoraMojo.java:215
Rollout step 4 edits the site home page by hand. If include::opendj:ROOT:partial$documentation-list.adoc[] lands on the line right after a paragraph, Asciidoctor reads the attribute entry as paragraph text. Antora 3.1.15 then renders both xrefs unresolved, with a literal {generated-documentation-component}. A plain list in the same spot still gives working links. Starting the partial with a blank line fixes it; I checked this in the same rendered site:
TextStringBuilder builder = new TextStringBuilder();
builder.appendNewLine();
builder.append(":generated-documentation-component: ").append(component).appendln(":");nitpick (non-blocking): The README example sets <antoraComponentName>opendj</antoraComponentName>, which is already the default for OpenDJ.
commons/doc-maven-plugin/README.md:49
The sentence before it says to set the option only when the name differs. An example with a different name, such as directory-service, would show that case and would not suggest that OpenDJ needs the override.
nitpick (non-blocking): The new README section does not say which plugin release first generates the partial and accepts the two options.
commons/doc-maven-plugin/README.md:37-55
A product pinned to an older plugin silently ignores <javadocUrl> and gets no partial; OpenDJ release tags pin it through ${commons.version}. Naming the first release lets a reader check which case they are in.
|
Addressed in the latest commit:
The doc plugin test suite passed (70 tests) with the reactor on JDK 17. |
maximthomas
left a comment
There was a problem hiding this comment.
praise: Round 1's feedback is addressed in the place it belongs, and each part is pinned.
- One
antoraComponentwithgetAntoraComponent()inAbstractAsciidocMojo(trim,Locale.ROOTdefault), called by bothAntoraMojo:205andAsciidocToPdfMojo:98. Its descriptor expression is pinned bytestDocumentationListOptionsAreDescriptorParameters(AntoraMojoTest.java:186-190), and the user-property and POM tests check that configuration reaches it (:123-184). - The partial's exact text is asserted (
AntoraMojoTest.java:82-89), including the leading blank line (AntoraMojo.java:207) that keeps the attribute entry out of an includer's paragraph.
question (non-blocking): Is OpenDJ sustaining/4.10.x expected to keep publishing docs to the site after rollout step 4?
commons/doc-maven-plugin/README.md:41-45
OpenDJ master's deploy.yml (:17-21, :325-341) also publishes builds of sustaining/4.10.x, with no branch condition: it runs rm -rf opendj/modules and then copies the build output. That branch pins commons 2.4.1 (pom.xml:38 at b12921ec), and its antora goal writes no documentation-list.adoc. Once the home page includes opendj:ROOT:partial$documentation-list.adoc, such a publish deletes the partial. Antora 3.1.15 then logs target of include not found and renders an "Unresolved include directive … include::opendj:ROOT:partial$documentation-list.adoc[]" paragraph in place of the OpenDJ list, until the next master publish; the site's baseline check would see a new Antora error. OpenAM, OpenIG and OpenIDM also publish their sustaining branches, so their lists follow whichever branch published last. If the answer is yes, step 4 needs a precondition: either stop that publish step for sustaining builds, or move sustaining/4.10.x to a commons release with this change. If the answer is no, nothing changes. The fix is in the rollout either way, not in this PR's code. Not run: a sustaining/4.10.x deploy (whether it gets past mvn deploy and the apidocs copy under JDK 8). No sustaining publish appears among the last 100 OpenDJ deploy runs.
suggestion (non-blocking): The generated index page is asserted with a single contains, so its heading and the removal of the old inline list are not pinned.
commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AntoraMojoTest.java:80-81
Two mutants survive with AntoraMojoTest 11/11 green. One drops the = <projectName> Documentation heading. The other keeps the old * xref:<doc>:index.adoc[] loop after the include, which lists every guide twice. The partial gets an exact check; the page should get one too:
assertThat(Files.readString(root.resolve("pages/index.adoc"), StandardCharsets.UTF_8)
.replace("\r\n", "\n"))
.isEqualTo("= OpenDJ Documentation\n\ninclude::partial$documentation-list.adoc[]\n\n");Pin: replaces :80-81. Both mutants turn it red.
suggestion (non-blocking): With javadocUrl set, the partial is checked only with order-free contains, so the Javadoc entry's position is not pinned.
commons/doc-maven-plugin/src/test/java/org/openidentityplatform/doc/maven/AntoraMojoTest.java:94-97, :144-146, :178-180
The exact check (:82-89) runs only on the first execution, which has no javadocUrl. Two mutants keep 11/11 green: one writes the link after :generated-documentation-component!:, the other before the attribute entry. In the first case the entry renders as a second list after the guides.
assertThat(Files.readString(root.resolve("partials/documentation-list.adoc"), StandardCharsets.UTF_8)
.replace("\r\n", "\n"))
.isEqualTo("\n:generated-documentation-component: directory-service:\n"
+ "ifeval::[\"{page-component-name}\" == \"directory-service\"]\n"
+ ":generated-documentation-component:\nendif::[]\n\n"
+ "* xref:{generated-documentation-component}reference:index.adoc[]\n"
+ "* xref:{generated-documentation-component}admin-guide:index.adoc[]\n"
+ "* link:/opendj/apidocs/index.html[API Reference (Javadoc)]\n\n"
+ ":generated-documentation-component!:\n");Pin: replaces :94-97. Both mutants turn it red.
question (non-blocking): Should a source partial that differs only in letter case, such as Documentation-List.adoc, fail the build on Linux too?
commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AntoraMojo.java:224-227
Files.exists(partialsPath.resolve("documentation-list.adoc")) follows the filesystem. On a default macOS volume (and by the same rule on default NTFS, which was not probed) Documentation-List.adoc trips the guard. On Linux CI it does not, and both files are published side by side. No OpenDJ, OpenAM, OpenIG or OpenIDM branch or latest release tag has such a name, so this is an edge case. If the answer is yes, a case-insensitive check over the listing makes every OS fail alike. Replace :225-227 and keep :224, because listPath is still written at :228; add import java.util.stream.Stream;:
try (Stream<Path> partials = Files.list(partialsPath)) {
if (partials.anyMatch(p -> p.getFileName().toString().equalsIgnoreCase("documentation-list.adoc"))) {
throw new MojoExecutionException("Cannot generate documentation-list.adoc: a source partial already uses this name");
}
}Pin: next to AntoraMojoTest.java:113-117, a source partial Documentation-List.adoc expecting the same MojoExecutionException. It is red on Linux without the change.
question (non-blocking): Is it intended that the product's own index needs antoraComponent to match the site component?
commons/doc-maven-plugin/src/main/java/org/openidentityplatform/doc/maven/AntoraMojo.java:210-216
At BASE the index wrote component-relative * xref:<doc>:index.adoc[], which resolved under any component name. At HEAD the links stay relative only when {page-component-name} equals getAntoraComponent(). Otherwise they become xref:<derived>:<doc>:index.adoc[] and render xref unresolved (Antora 3.1.15) on the product's own index. All four current consumers lowercase to their site component, so no build changes today. If it is intended, README:47 should say what happens otherwise ("…otherwise the guide links on the product's own index do not resolve").
nitpick (non-blocking): "The Javadoc URL is used as supplied and does not vary by documentation version" does not hold for a page-relative URL.
commons/doc-maven-plugin/README.md:55-56
The value is trimmed (AntoraMojo.java:218). A page-relative value such as apidocs/index.html resolves against each page that includes the list: /opendj/4.10/apidocs/ on the 4.10 index, /opendj/apidocs/ on the latest one and /apidocs/ on the site home. Suggested text: "The Javadoc URL is written into every version's list as given, without surrounding whitespace. Use a root-relative or absolute URL: a page-relative one resolves against each page that includes the list."
nitpick (non-blocking): The include example names opendj:, while the configuration example below it sets directory-service, and nothing connects the two.
commons/doc-maven-plugin/README.md:45, :51
After :45: "opendj is the component name: <antoraComponent> when set, otherwise the lowercased <projectName>."
nitpick (non-blocking): The section does not mention the new failure on an existing partials/documentation-list.adoc.
commons/doc-maven-plugin/README.md:47-49
AntoraMojo.java:226 now fails with "Cannot generate documentation-list.adoc: a source partial already uses this name"; only the PR description mentions it. After :49: "The goal fails if the sources already contain partials/documentation-list.adoc."
|
Addressed in the latest commit:
I left the filename check case-sensitive on case-sensitive filesystems: differently cased names are distinct there, and the current consumers do not have such a collision. The doc plugin test suite passed (70 tests) with the reactor on JDK 17. |
maximthomas
left a comment
There was a problem hiding this comment.
praise: This round resolves the previous review's README and test comments.
AntoraMojoTest.testGeneratedRootPageUsesReusableDocumentListnow compares the generated index page and thedirectory-service+ Javadoc partial exactly (AntoraMojoTest.java:80-82,:95-103). That pins the heading, the removal of the old inline list and the Javadoc entry's position. The class passes 11/11 at cf60d97 on JDK 17.README.md:66-70and rollout step 4 require every branch that can publish the product's docs to be checked before the home-page include is added. That covers a publish from an older sustaining branch.README.md:57-61states that the Javadoc URL is trimmed, is not adjusted per version, and must be root-relative or absolute.
Add links to guides already published on the product documentation indexes but missing from the home page: - OpenDJ: Release Notes, Getting Started and How-To Guides. - OpenAM: Release Notes. - OpenIG: How-To Guides. This manual update aligns the guide lists while the reusable documentation list from OpenIdentityPlatform/commons#389 is being rolled out. The OpenIG home-page link also appears in #45, which adds the guide to the product navigation and PDF mapping. Validation: `npm run build` completed with exit code 0. The generated home page contains all five links, their generated targets exist, and their published URLs returned HTTP 200. Antora reported warnings and the existing OpenIG 5.3.2 error recorded in `.github/build-baseline/antora-errors.txt`.
Problem
The documentation site currently maintains two independent lists of guides for each product: a handwritten list on the site home page and a product index generated by the
antoragoal from that product's Maven<documents>configuration.For example, the OpenDJ sections differ today:
The documentation home page links to Javadoc, but omits Release Notes, Getting Started and How-To Guides.
The OpenDJ documentation index includes those three guides, but omits the Javadoc link.
Readers therefore see different choices depending on where they enter the documentation, and every new or removed guide must be kept in sync manually.
The product index in the documentation repository is generated: the OpenDJ deployment replaces
opendj/moduleswith the Maven build output. Editing that index in the site repository alone would be lost on the next upload.Change
Generate
ROOT/partials/documentation-list.adocfrom the existing<documents>list and include it in the generated product index. The site home page can include the same partial, leaving the product's build configuration as the single source for guide order and membership. An optionaljavadocUrladds the API reference to that list. The existingantoraComponentsetting is shared withasciidoc-to-pdfand overrides the lowercased project name when needed.Within a product component, guide links resolve against the current documentation version. When the partial is included from another component, they resolve against the latest product version. The configured component name and Javadoc URL are trimmed. The Javadoc URL is written unchanged apart from trimming, so a page-relative URL resolves against the including page; use a root-relative or absolute URL for a stable target. The generator fails if a source partial already uses the generated filename, rather than silently overwriting it.
Rollout after updating commons
javadocUrlas/opendj/apidocs/index.htmland setantoraComponentonly if the component name differs from the default. Keep the guide list in OpenDJ's<documents>configuration and build its documentation.opendj/modules, including the generated index and partial. Verify that the partial and Javadoc are present and that the OpenDJ index renders correctly.include::opendj:ROOT:partial$documentation-list.adoc[], build the site, and verify both pages, the links and older documentation versions.Validation
mvn -o -Dmaven.repo.local=/private/tmp/commons-pr389-m2 -pl commons/doc-maven-plugin -am test(JDK 17) — 70 doc plugin tests passed; the reactor also passed.