Skip to content

Generate a reusable Antora documentation list - #389

Merged
vharseko merged 3 commits into
OpenIdentityPlatform:masterfrom
vharseko:shared-documentation-list
Nov 8, 2026
Merged

vharseko merged 3 commits into
OpenIdentityPlatform:masterfrom
vharseko:shared-documentation-list

Conversation

@vharseko

@vharseko vharseko commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

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 antora goal from that product's Maven <documents> configuration.

For example, the OpenDJ sections differ today:

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/modules with 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.adoc from 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 optional javadocUrl adds the API reference to that list. The existing antoraComponent setting is shared with asciidoc-to-pdf and 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

  1. Release a commons version containing this change.
  2. Update OpenDJ to that version. Configure javadocUrl as /opendj/apidocs/index.html and set antoraComponent only if the component name differs from the default. Keep the guide list in OpenDJ's <documents> configuration and build its documentation.
  3. Publish the OpenDJ documentation to the site repository. The existing upload replaces opendj/modules, including the generated index and partial. Verify that the partial and Javadoc are present and that the OpenDJ index renders correctly.
  4. Before updating the home page, ensure that every branch which can publish OpenDJ docs either produces the partial and an appropriate current list, or cannot replace the published modules. In particular, a sustaining-branch deployment with an older plugin could delete the partial. Check Java compatibility before upgrading the plugin on such a branch. Then replace the handwritten OpenDJ list on the home page with include::opendj:ROOT:partial$documentation-list.adoc[], build the site, and verify both pages, the links and older documentation versions.
  5. Repeat the product update, documentation publication, publishing-branch check and home-page change for OpenAM, OpenIG and OpenIDM as each product adopts the new plugin. Each product can configure its own Javadoc URL. The sidebar navigation remains separately configured and is not synchronized by this change.

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.
  • Tests cover the complete generated index and partial (including Javadoc placement), parameter descriptors, Maven configuration and user properties, whitespace, and the locale-independent default.
  • Before the review changes, built a small Antora site with two versions of a product to check that the home page links to the latest guide, each product page links to its own version, and the configured Javadoc link is rendered.

@vharseko vharseko added enhancement documentation Documentation and Javadoc changes java Pull requests that update java code labels Nov 7, 2026
@vharseko
vharseko requested a review from maximthomas November 7, 2026 13:27
@vharseko vharseko added the tests Test code changes label Nov 7, 2026

@maximthomas maximthomas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

praise: The list is generated where the index already was, and the version handling holds up in a rendered site.

  • AntoraMojo.createIndexForRoot builds the partial from <documents>, and the products' deploy workflows (rm -rf <product>/modules, then cp -R …/antora/modules) publish it together with the index.
  • The ifeval on {page-component-name} works under Antora 3.1.15. In a rendered two-version site, the ROOT home page links to the latest guides and opendj/4.10/index.html links to reference/index.html inside 4.10.
  • Files.exists(listPath) throws a MojoExecutionException instead 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.

@vharseko

vharseko commented Nov 8, 2026

Copy link
Copy Markdown
Member Author

@maximthomas

Addressed in the latest commit:

  • Both goals now use the existing antoraComponent setting. Component names and Javadoc URLs are trimmed, with blank component names falling back to the locale-independent default.
  • The generated partial starts with a blank line, and its complete structure is checked by the test.
  • Tests cover the parameter descriptors, Maven configuration and user properties, whitespace, and the default under a Turkish locale. The PDF configuration test also checks the shared component setting.
  • The README uses a non-default component in its example and marks the feature as unreleased. The first release number can be added once it is known.

The doc plugin test suite passed (70 tests) with the reactor on JDK 17.

@vharseko
vharseko requested a review from maximthomas November 8, 2026 09:51

@maximthomas maximthomas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

praise: Round 1's feedback is addressed in the place it belongs, and each part is pinned.

  • One antoraComponent with getAntoraComponent() in AbstractAsciidocMojo (trim, Locale.ROOT default), called by both AntoraMojo:205 and AsciidocToPdfMojo:98. Its descriptor expression is pinned by testDocumentationListOptionsAreDescriptorParameters (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."

@vharseko

vharseko commented Nov 8, 2026

Copy link
Copy Markdown
Member Author

@maximthomas

Addressed in the latest commit:

  • The rollout instructions now require checking every documentation-publishing branch before adding the site include. An older sustaining build can remove the partial; upgrading such a branch also requires checking its Java compatibility. The same check applies to each product.
  • The generated index and the partial with Javadoc now have complete output assertions, including the heading, absence of the old inline list, and Javadoc placement.
  • The README explains how the include component relates to antoraComponent, the effect of a mismatch, URL trimming and page-relative URLs, and the failure on an existing partials/documentation-list.adoc.

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.

@vharseko
vharseko requested a review from maximthomas November 8, 2026 11:44

@maximthomas maximthomas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

praise: This round resolves the previous review's README and test comments.

  • AntoraMojoTest.testGeneratedRootPageUsesReusableDocumentList now compares the generated index page and the directory-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-70 and 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-61 states that the Javadoc URL is trimmed, is not adjusted per version, and must be root-relative or absolute.

@vharseko
vharseko merged commit 720d3be into OpenIdentityPlatform:master Nov 8, 2026
13 of 14 checks passed
@vharseko
vharseko deleted the shared-documentation-list branch November 8, 2026 12:44
vharseko added a commit to OpenIdentityPlatform/doc.openidentityplatform.org that referenced this pull request Nov 8, 2026
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`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation and Javadoc changes enhancement java Pull requests that update java code tests Test code changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants