Generate javadocs

[keski]

This pull request modifies the pom files to generate javadoc. The aggregated javadoc is placed in docs/javadoc/<version> and docs/javadoc/latest. This change has been merged into gh-pages and javadocs are now published and linked from the website.

Generation of javadoc is in a separated profile and does not affect the regular build process. To generate locally use:

mvn clean package -Pgenerate-javadoc -DskipTest

Note: The code is still missing a lot of the required javadoc annotations and the log will contain a lot of warnings/errors.

[hartig]

Looks good. I am happy to merge this PR. However, I have a question about:

This change has been merged into gh-pages

So, gh-pages already contains the same changes as given in this PR?

and javadocs are now published and linked from the website.

How is the creation of the Javadocs in gh-pages triggered?

(PS. I am traveling these weeks. Hence, my slow replies.)

[hartig]

One more question: I observe that generating the Javadocs results in docs/ sub-directories within each of the directories of the modules (e.g., ./hefquin-base/docs/). Is it possible to put these sub-directories under the respective target/ sub-directories (e.g., ./hefquin-base/target/docs/) such that they will also be removed when doing mvn clean?

[keski]

Looks good. I am happy to merge this PR. However, I have a question about:

This change has been merged into gh-pages

So, gh-pages already contains the same changes as given in this PR?

Yes, this is the pom.xml file that is currently being used in gh-pages. Note that the gh-pages commit history is not very pretty but we will keep all shared files in synch with main.

and javadocs are now published and linked from the website.

How is the creation of the Javadocs in gh-pages triggered?

(PS. I am traveling these weeks. Hence, my slow replies.)

The creating of the pages is triggered by the a dedicated workflow publish_docs.yml, which is triggered whenever there is a push to gh-pages.

[keski]

One more question: I observe that generating the Javadocs results in docs/ sub-directories within each of the directories of the modules (e.g., ./hefquin-base/docs/). Is it possible to put these sub-directories under the respective target/ sub-directories (e.g., ./hefquin-base/target/docs/) such that they will also be removed when doing mvn clean?

I agree this is a bit annoying and I haven't been able to make it work. I'll change the pom.xml file so that javadoc is generated in target and then I'll just add a line to the workflow to copy it to its final location instead of specifying it as part of the configuration.

[hartig]

Two follow-up questions:

How is the creation of the Javadocs in gh-pages triggered?

The creating of the pages is triggered by the a dedicated workflow publish_docs.yml, which is triggered whenever there is a push to gh-pages.

How is the latter configured? Did you create a Github action for it?

I'll change the pom.xml file so that javadoc is generated in target and then I'll just add a line to the workflow to copy it to its final location instead of specifying it as part of the configuration.

Have you done that now with the recent commit (https://github.com/LiUSemWeb/HeFQUIN/pull/360/commits/13432db949d0fbd127f937ec1affcf944ea7cc85)? (I ask because the commit contains changes only to the POM file, not to "the workflow".

[keski]

Two follow-up questions:

How is the creation of the Javadocs in gh-pages triggered?

The creating of the pages is triggered by the a dedicated workflow publish_docs.yml, which is triggered whenever there is a push to gh-pages.

How is the latter configured? Did you create a Github action for it?

The workflow publish_docs.yml is only updated in the gh-pages branch.

I'll change the pom.xml file so that javadoc is generated in target and then I'll just add a line to the workflow to copy it to its final location instead of specifying it as part of the configuration.

Have you done that now with the recent commit (13432db)? (I ask because the commit contains changes only to the POM file, not to "the workflow".

Javadocs are now built as part of the normal mvn package command and cleaned up with mvn clean. The actions defined in publish_docs.yml now copies javadoc from target/ into the appropriate docs/ directory, and no longer relies on the pom.xml for that.

[hartig]

How is the creation of the Javadocs in gh-pages triggered?

The creating of the pages is triggered by the a dedicated workflow publish_docs.yml, which is triggered whenever there is a push to gh-pages.

How is the latter configured? Did you create a Github action for it?

The workflow publish_docs.yml is only updated in the gh-pages branch.

I don't think this answers my question. My question was: How is the execution of the publish_docs.yml triggered? Did you create a Github Action that triggers this execution each time there is a commit to the gh-pages branch? Or does the execution need to be triggered manually?

[keski]

I don't think this answers my question. My question was: How is the execution of the publish_docs.yml triggered? Did you create a Github Action that triggers this execution each time there is a commit to the gh-pages branch? Or does the execution need to be triggered manually?

The workflow publish_docs.yml is triggered automatically each time there is a push to the gh-pages branch:

name: Publish documentation
run-name: Build
on:
  push:
    branches:
      - gh-pages
...

It uses and customizes some predefined actions (actions/checkout@v3, actions/setup-java@v2 and ad-m/github-push-action@master), but the entire pipeline itself is not defined as an action that can be triggered manually. The workflow commits changes to docs/ in gh-pages, which then triggers the the action that publishes the pages from docs/ to https://liusemweb.github.io/HeFQUIN/.

[hartig]

Thanks for answering my question. Now I get it! I didn't see that publish_docs.yml is in the .github/workflows/ directory.

I will merge this PR now (and will hopefully manage to look at the other things latest tomorrow).