[#22] Link API docs (Javadoc) from the start page and the Projects menu

[vharseko]

Fixes #22

Changes

• ROOT/modules/ROOT/pages/index.adoc (start page):

  • an "API Reference (Javadoc)" link at the end of the guide list of each of the four products;
  • a new "API Reference (Javadoc)" section (#api-reference) with Products (OpenDJ, OpenAM, OpenIG, OpenIDM) and Libraries: OpenICF and Commons, whose Javadoc was reachable only by URL.

  The links are root-relative (/openam/apidocs/index.html), because the Javadoc is not an Antora page but is copied into the site by npm run copyApiDocs.

• supplemental-ui/partials/header-content.hbs: a divider and an "API Reference (Javadoc)" entry in the Projects menu, pointing to that section.

Component navigation is not changed: the product release workflows replace <product>/modules (rm -rf) on every docs upload, so an entry added there in this repository would be lost; it would have to come from the product repositories.

Verification

Local Antora build of this branch (with copyApiDocs):

• all six targets (openam, opendj, openidm, openig, openicf, commons /apidocs/index.html) exist in the generated site;
• the menu entry resolves from every page, e.g. ./#api-reference on the start page and ../../#api-reference on openam/admin-guide/;
• lychee --offline: no broken link on the start page; the site total is unchanged (45, all known and tracked);
• no new Antora errors;
• the branch is rebased onto master after [#21] Fix broken JEE agent PDF link and malformed header markup #27 and Fix Dependabot alerts: pin js-yaml to 4.3.2 #35, without conflicts.

In CI, a missing <dir>/apidocs/index.html target is caught by the lychee check of #28; a renamed #api-reference anchor by its --include-fragments run proposed in #36.

[maximthomas]

praise: The links point exactly where the Javadoc copies land, and the menu entry reuses the existing URL helper.

• all six <dir>/apidocs/index.html targets exist at the head, and copyApiDocs (package.json:7) copies them to the matching /<dir>/apidocs/index.html site paths, so OpenICF and Commons get their first link (ROOT/modules/ROOT/pages/index.adoc:82-83)
• the Projects-menu entry goes through relativize (resolvePageURL 'ROOT::index.adoc') like the four product entries above it (supplemental-ui/partials/header-content.hbs:49), and the start page renders <h2 id="api-reference"> for index.adoc:70-71

---

suggestion (non-blocking): Nothing fails the build if the new apidocs links or the #api-reference anchor break.

ROOT/modules/ROOT/pages/index.adoc:70, :28, :44, :54, :67, :75-83; supplemental-ui/partials/header-content.hbs:49; package.json:7

Antora resolves neither link: targets nor the fragment in the hbs href, and the only workflow, .github/workflows/publish.yml, runs npm run buildAll on push to master with no link check. Two changes keep the build green and ship a broken link: renaming [#api-reference] (the menu entry then lands at the top of the start page), and cp -R ./openicf/apidocs build/site/openicf in copyApiDocs (/openicf/apidocs/index.html returns 404). The gap predates this PR; the links are correct today.

# a step after `npm run buildAll` in a pull_request job
- run: |
    grep -q 'id="api-reference"' build/site/index.html
    for d in opendj openam openig openidm openicf commons; do
      test -f "build/site/$d/apidocs/index.html"
    done

Pin: the grep turns red on the anchor rename, the test -f on the moved openicf copy. Or: if #28 lands, its lychee gate (--root-dir /site, run after copyApiDocs) already catches the moved copy; the anchor still needs the grep, since that gate runs without --include-fragments.

---

issue (non-blocking): The new CDDL header's only ownership line is a "Portions Copyright", with no original copyright line.

ROOT/modules/ROOT/pages/index.adoc:1-15

"Portions" presupposes an original Copyright line above it; every other CDDL-headed file in the repository has one (e.g. Copyright 2015 ForgeRock AS. followed by Portions Copyright 2024-2026 3A Systems LLC.). This page was created in this repository in 2024 (735ee41), and no other ROOT page carries a header, so the block names no holder for the existing content. Neither the description nor the commit message mentions the header; rendering is unaffected.

-////
-The contents of this file are subject to the terms of the Common Development and
-...
-Portions Copyright 2026 3A Systems, LLC.
-////
 = Open Identity Platform Documentation

Or: keep the header with an original line for the existing content, e.g. Copyright 2024-2026 3A Systems LLC., if 3A Systems holds it.

[vharseko]

@maximthomas

Re: CI check for the apidocs links and #api-reference — no change in this PR; both cases are covered by the CI work already open:

• missing apidocs targets: [#25] CI: build pull requests and make the site build reproducible #28's lychee step (--root-dir /site, after copyApiDocs) checks them. --exclude-path only skips the apidocs pages as inputs, not as link targets. Checked with lychee 0.24.2 and [#25] CI: build pull requests and make the site build reproducible #28's options: a link to an absent /commons/apidocs/index.html fails with File not found;
• the renamed anchor: CI: check the anchors of links in the pull request build #36 adds --include-fragments; with it the same check fails a link to a renamed id with Cannot find fragment.

Re: the CDDL header — agreed; removed in 6b2c620. The page had no header, and no other ROOT page has one; the header also points to legal/CDDLv1.0.txt, which this repository does not have.

The branch is also rebased onto the current master (after #27 and #35); no conflicts.

[maximthomas]

praise: The rebased head matches the description, and both entry points lead to the same section.

• The CDDL header block is gone from ROOT/modules/ROOT/pages/index.adoc, so the page again starts at its doctitle and the diff stays within the stated scope.
• supplemental-ui/partials/header-content.hbs:49 uses the same relativize (resolvePageURL 'ROOT::index.adoc') call as the four Projects entries at :45-47. Its #api-reference fragment matches [#api-reference] at ROOT/modules/ROOT/pages/index.adoc:55.
• All six targets linked from the start page (opendj, openam, openig, openidm, openicf, commons /apidocs/index.html) exist in the head tree.