OpenLiberty / docs-javadoc

Contains the various javadoc published on https://openliberty.io

Open Liberty Javadoc

This repository contains the Javadoc that is published on https://openliberty.io, including the following models:

• Open Liberty APIs
• Open Liberty SPIs
• MicroProfile APIs
• Jakarta EE APIs
• Java EE APIs

MicroProfile and Jakarta API documentation is updated with each major release from those platforms. The Open Liberty API and SPI documentation is updated with each 4-week release of the runtime.

Preparing Open Liberty API and SPI Javadoc files for publication

The following steps document the procedure the Open Liberty Docs team follows to prepare the Open Liberty API and SPI Javadoc files for publication with each release.

Complete these steps 2-3 days before the release to ensure that you have time to verify the Javadoc on the staging site. However, the Javadoc doesn't appear on the staging site until after the other autogenerated files for the release are committed to the staging branch of the docs-generated repository and the resulting staging site build finishes. The autogenerated files are typically added to the staging branch of the docs-generated repo 1-2 days before the release.

1. Clone the docs-javadoc repository.

2. Get the generated com.ibm.openliberty.javadoc.doc.jar file from the Liberty GM build.

3. Change the extension of the file from com.ibm.openliberty.javadoc.doc.jar to com.ibm.openliberty.javadoc.doc.zip.

4. Extract the com.ibm.openliberty.javadoc.doc.zip to a temporary directory on your local machine.

5. Create a branch off the prod branch of docs-javadoc and give it a descriptive name.

6. In the modules/reference directory of the docs-javadoc repository, create a new folder and name it based on the version for that release, for example modules/reference/23.0.0.7.

7. Copy all the -javadoc folders from your local extracted copy of the com.ibm.openliberty.javadoc.doc folder into the new modules/reference/<version> folder that you created in the previous step.

8. Commit your changes to the branch that you created in step 5.

9. Create a pull request from your branch to staging. Do not add the files to draft.

10. Get the PR reviewed by a docs team member and merge it.

11. Add the javadoc nav file and iframe files to the docs-generated repo.

    a. In the docs-generated repo, create a new vNext-based branch and give it a descriptive name.

    b. Copy the feature-nav-api-openliberty.adoc and feature-nav-spi-openliberty.adoc files from the nav directory of your local extracted copy of the com.ibm.openliberty.javadoc.doc folder to the modules/reference/partials directory in the docs-generated repo.

    c. Copy the api and spi directories from the iframe directory of your local extracted copy of the com.ibm.openliberty.javadoc.doc folder to the modules/reference/pages/javadoc directory in the docs-generated repo.

    d. Create a PR from your working branch to the draft branch of the docs-generated repo, get it reviewed and merge it in.

    e. Create a PR from the draft branch to the staging branch of the docs-generated repo, get it reviewed and merge it in.

12. Verify the updated Javadoc on the docs staging site. The Javadoc doesn't appear on the staging site until after the autogenerated files for the release are committed to the staging branch of the docs-generated repository and the resulting staging site build finishes. The autogenerated files are typically added to the staging branch of the docs-generated repo 1-2 days before the release.

13. In the docs-javadoc repository, create a PR from the staging branch into the prod branch.

14. Get the PR reviewed by a docs team member and merge it.

The updated Javadoc publishes to openliberty.io with the rest of the 4-week release. For more information about the publishing process, see Publishing a new release of the open Liberty Docs.