chore: Enable JavaDoc Aggregate with Delombok

[newtork]

Context

Follow up from
#866

Backlog:
https://github.com/SAP/cloud-sdk-java-backlog/issues/482

Workflow:
https://github.com/SAP/cloud-sdk-java/actions/workflows/javadoc.yaml

Generated PR in Documentation Portal:
SAP/cloud-sdk#2274

Feature scope:

• JavaDoc Aggregate
  • Update to 3.12.x https://github.com/SAP/cloud-sdk-java-backlog/issues/490
  • Delombok
  • Disallow list
• Make part of (prepare) release process
• Hide non-production modules

  PROJECTS: "!:rfc,!:dwc-cf,!:datamodel-metadata-generator,!:odata-generator,!:odata-generator-maven-plugin,!:odata-generator-utility,!:odata-v4-generator,!:odata-v4-generator-maven-plugin,!:s4hana-connectivity,!:soap,!:testutil,!:s4hana-core" 
  

Usage

In upcoming dedicated workflow:

1. Clone repo
2. Install locally
3. Run Delombok
4. Replace source code with delombok'ed generated code
5. Run Javadoc
6. (Not depicted: Upload to documentation portal)

git clone --branch rel/5.24.0 --single-branch https://github.com/SAP/cloud-sdk-java.git
cd cloud-sdk-java

mvn install -DskipTests

PROJECTS='!:rfc,!:dwc-cf,!:datamodel-metadata-generator,!:odata-generator,!:odata-generator-maven-plugin,!:odata-generator-utility,!:odata-v4-generator,!:odata-v4-generator-maven-plugin,!:s4hana-connectivity,!:soap,!:testutil,!:s4hana-core'

mvn process-sources -Drelease --fail-at-end --projects $PROJECTS

find . -type d -path "*/target/delombok" -exec sh -c 'cp -r "$1"/* "$(dirname $(dirname "$1"))/src/main/java/"' _ {} \;

mvn clean javadoc:aggregate -Drelease -Djava.failOnWarning=false -Djavadoc.sourcepath=src/main/java --projects $PROJECTS

Find HTML in ./target/reports/apidocs/

Sample output

apidocs.zip

See Screenshot

Definition of Done

• Functionality scope stated & covered
• Tests cover the scope above
• Error handling created / updated & covered by the tests above
• Documentation updated
• Release notes updated

[CharlesDuboisSAP]

Why did you create a standalone job instead of putting it into the release like it was before?

[newtork]

Why did you create a standalone job instead of putting it into the release like it was before?

It allows for custom branch/tag selection, but primarily because I felt like I don't want to add another point of failure to the release job again. :/

It's a bit awkward we have so many secondary actions in the release, that are technically not functional requirements. But they break the process if something goes wrong.

I'm okay with putting it to the release process, but maybe we can find a way to address this concern in the future.

[Jonas-Isr]

I like the outlook of having a slimmer release process. It makes both troubleshooting and rerunning the workflow(s) faster. The downside is that it is slightly less automation then, i.e., one more button press the releasing person has to do themself. I would still be of the opinion that having it as a separate workflow is better. If we want to have an aggregated javadoc created for each release, we should then add an additional point to the release PR message in the prepare-release workflow.

[Jonas-Isr]

Minor points, besides that I like it :)

[Jonas-Isr]

We should add a TODO to the PR created in the prepare-release workflow to review, approve, and merge this JavaDoc PR after the release.

[newtork]

Since the workflow is triggered async, I can't put a direct URL to the upcoming JavaDoc PR.
However I used a generic link which should suffice, IMHO

[Jonas-Isr]

LGTM