Project documentation setup

[zero88]

• Fix GHA/gradle build to publish correct version for each sub-project: jpa-ext, rsql, jooqx
• Add :docs:asciidoc, :docs:testing-asciidoc and :rsql:asciidoc to main branch
  • Use Antora as component documentation per each project
  • Add AntoraDocComponent plugin. (Done then will merged to Antora plugin play-iot/gradle-plugin#20)
  • Asciidoc gen for code example
  • [ ] Publish docs artifact to nexus
• Add Antora playbook and add it as git sub-modules
• Support doc versioning
  • Reserve git document tag/branch for each project when release
  • Include main branch for development doc
• GitHub Workflow pipeline
  • In current build step, add step to trigger build docs.yml by workflow_dispatch.
  • Add GitHub workflow: docs.yml
    • build document for each project based on the workflow_dispatch_input
    • Commit and push to the corresponding branch
    • Trigger the aggregate docs workflow in playbook
      • publish document to Github page
• Add Antora custom UI with search function with lunr search (docsearch still in request)
• Release pipeline
  • Changelog setup https://github.com/github-changelog-generator Done in Add changelog generator gh-project-context#38
  • Convert CHANGELOG.md to .adoc https://github.com/bodiam/markdown-to-asciidoc
  • Trigger playbook build step after release by workflow_dispatch with rsql version and jooqx version
• Clean up redundant documents

Deprecated

• Remove :docs project in main branch
• [x] Add new branch to generate document #78
  • [ ] Use rsql version and jooqx version to gather lib artifact and javadoc jar
  • [ ] Use only :sample:model and :sample:web project to build database model to create :example
  • [ ] Build Asciidoc with :example
  • [ ] Extract javadoc jar

[zero88]

The current status: https://zero88.github.io/jooqx/usage/

[zero88]

Antora for static generator from ascii doc

• Search feature
  • https://github.com/SUSE/doc-susemanager/wiki/Setup-Algolia-Search-with-Antora
  • https://gitlab.com/antora/antora-ui-default/-/issues/44

[zero88]

https://vuepress.vuejs.org/ for markdown doc. Example: https://reactiverse.io/es4x/

[zero88]

Antora playbook cannot inject an extension in contentAggregate process to customize action after git checkout, but before component validation.

=> need to build and keep-track document output on docs/* git branch.

Another solution is to add a build step in beforeProcess to checkout git project, build project, and process doc in local mode.
But requires too much work and needs to handle versioning.

[zero88]

New features in GitHub workflow: https://docs.github.com/en/actions/using-workflows/reusing-workflows

[zero88]

Antora UI showcase https://gitlab.com/antora/antora.org/-/issues/20

[zero88]

gh-project-context with changelog generator zero88/gh-project-context#38