Skip to content

[#1129] Point the guides' Javadoc links at the published apidocs, and resolve {opendj-version} in the uninstall and monitoring pages - #1140

Open
vharseko wants to merge 1 commit into
OpenIdentityPlatform:masterfrom
vharseko:issue-1129
Open

vharseko wants to merge 1 commit into
OpenIdentityPlatform:masterfrom
vharseko:issue-1129

Conversation

@vharseko

Copy link
Copy Markdown
Member

Fixes #1129

Problem

  • Javadoc links. The guides link to ../javadoc/index.html (and ../javadoc/index.html?org/…/X.html), which is 404 on the site: the Javadoc is published at https://doc.openidentityplatform.org/opendj/apidocs/. That Javadoc is the frameless kind, so the index.html?<class page> form would only open the overview there, not the class.
  • {opendj-version}. The asciidoc-pre-process goal of doc-maven-plugin (AsciidocPreProcessMojo.updateVersionAttributes) resolves the version only by rewriting a :opendj-version: x.y.z line on the page itself. install-guide/chap-uninstall.adoc has no such line, so msiexec /x opendj-{opendj-version}.msi /quiet stays literal. admin-guide/chap-monitoring.adoc defines the attribute, but its OpenDMK console block (unzip opendj-{opendj-version}.zip) has no subs="attributes", and a listing block does not substitute attributes by default.

Change

  • server-dev-guide/chap-writing-plugins.adoc (4 links) and reference/appendix-interface-stability.adoc (1 link): point at https://doc.openidentityplatform.org/opendj/apidocs/: index.html for the API as a whole, and the class page itself for PluginType, DirectoryServerPlugin and PasswordValidator. The links are absolute so that they also work in the PDF build.
  • install-guide/chap-uninstall.adoc: define :opendj-version: x.y.z, which the pre-processor rewrites like on the other pages.
  • admin-guide/chap-monitoring.adoc: subs="attributes" on the OpenDMK console block, as on the other blocks of that page that use the attribute.

Verification

  • All four new URLs answer 200. https://doc.openidentityplatform.org/opendj/javadoc/index.html answers 404.
  • Rendered the four pages with AsciidoctorJ (asciidoctor 2.0.17) after applying the pre-processor's :opendj-version: rewrite, on master and on this branch:
    • master: {opendj-version} stays literal once in chap-uninstall.html and once in chap-monitoring.html, and 5 hrefs point at ../javadoc/….
    • this branch: no literal {opendj-version} is left (msiexec /x opendj-5.1.1.msi /quiet, unzip opendj-5.1.1.zip), and all 5 hrefs point at …/opendj/apidocs/….
  • A scan of every .adoc under opendj-doc-generated-ref/src/main/asciidoc finds no other page that uses {opendj-version} / {opendj-version-short} without defining it, and no other listing block that uses them without subs.

No test is added: the change is documentation only.

…blished apidocs, and resolve {opendj-version} in the uninstall and monitoring pages
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: broken Javadoc links and unresolved {opendj-version}

1 participant