Publish all project documentation on smallrye.io, from the projects' repositories

.github/workflows/build.yml

@@ -20,7 +20,7 @@ on:
       - 'NOTICE'
       - 'README*'
   # Daily, so a post dated later than the merge publishes on its date
-  # (future-dated posts are left out until then), and the docs pick up new releases.
+  # (future-dated posts are left out until then).
   schedule:
     - cron: "0 6 * * *"
   workflow_dispatch:
@@ -34,33 +34,13 @@ jobs:
   build:
     runs-on: ubuntu-latest
 
-    services:
-      kroki:
-        image: yuzutech/kroki
-        env:
-          KROKI_MERMAID_HOST: kroki-mermaid
-        ports:
-          - 8000:8000
-      kroki-mermaid:
-        image: yuzutech/kroki-mermaid
-
     steps:
       - name: checkout
         uses: actions/checkout@v4
         with:
           # The sitemap plugin reads each page's last change from git history.
           fetch-depth: 0
 
-      # Before the site: the Roq build leaves a node_modules/ in the repository root, and
-      # npm would install Antora there instead of in docs/.
-      - name: generate docs
-        run: |
-          cd docs
-          # asciidoctor-kroki must stay on 0.18.1: since 1.0.0, its extensions are
-          # async and require Asciidoctor.js 4, while Antora 2.3 uses Asciidoctor.js 1.5.9
-          npm i @antora/cli@2.3 @antora/site-generator-default@2.3 asciidoctor-kroki@0.18.1
-          ./node_modules/@antora/cli/bin/antora --stacktrace generate antora-playbook.yml
-
       - name: generate website
         uses: quarkiverse/quarkus-roq@v1.1
         with:
@@ -72,8 +52,27 @@ jobs:
       - name: put the stylesheet in the pages
         run: java .github/InlineStyles.java target/roq
 
-      - name: add docs to the website
-        run: cp -r docs/build/site target/roq/docs
+      # GitHub Pages cannot redirect: the documentation addresses this site published before
+      # (Antora's /docs/<project>/<release>/<page>.html) get small redirect pages.
+      - uses: jbangdev/setup-jbang@2b1b465a7b75f4222b81426f23a01e013aa7b95c # v0.1.1
+        with:
+          version: 0.138.0
+
+      # An older documentation version stores only the pages that differ from the next newer version:
+      # write the others, each in its own version's frame.
+      - name: add the documentation pages versions share
+        run: jbang tools/docs/Docs.java inherit target/roq
+
+      # Search for the documentation pages: a static index per project, filtered by version.
+      - name: index the documentation for search
+        run: tools/docs/search-index.sh target/roq
+
+      - name: add redirects for moved documentation
+        run: jbang tools/docs/Docs.java redirects target/roq
+
+      # A link to a page that is not in the site fails the build.
+      - name: check the links between pages
+        run: jbang tools/docs/Docs.java links target/roq
 
       - name: attach website
         uses: actions/upload-artifact@v4

.github/workflows/docs-check.yml

@@ -0,0 +1,104 @@
+name: Check project documentation
+
+# Reusable: a SmallRye project calls this on pull requests that touch its docs. It renders the
+# pull request's AsciiDoc with the smallrye.io site exactly as it will be published, fails on a
+# missing include, a page that does not render or a broken link, and attaches the rendered docs as
+# an artifact.
+#
+#   jobs:
+#     docs:
+#       uses: smallrye/smallrye.github.io/.github/workflows/docs-check.yml@develop
+#       with:
+#         project: smallrye-graphql      # the key in smallrye.github.io data/docs.yml
+
+on:
+  workflow_call:
+    inputs:
+      project:
+        description: 'Project key in data/docs.yml'
+        type: string
+        required: true
+
+# It renders pull-request content: read-only, no secrets.
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    # Diagram blocks ([mermaid], [plantuml], ...) are rendered to SVG by the sync (tools/docs/Docs.java).
+    services:
+      kroki:
+        image: yuzutech/kroki
+        env:
+          KROKI_MERMAID_HOST: kroki-mermaid
+        ports:
+          - 8000:8000
+      kroki-mermaid:
+        image: yuzutech/kroki-mermaid
+    env:
+      KROKI_URL: http://localhost:8000
+    steps:
+      - name: checkout the project
+        uses: actions/checkout@v4
+        with:
+          path: project
+
+      - name: checkout smallrye.io
+        uses: actions/checkout@v4
+        with:
+          repository: smallrye/smallrye.github.io
+          ref: develop
+          path: site
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+          cache-dependency-path: site/pom.xml
+
+      - uses: jbangdev/setup-jbang@2b1b465a7b75f4222b81426f23a01e013aa7b95c # v0.1.1
+        with:
+          version: 0.138.0
+
+      # The tool finds the site from the working directory, so it runs inside the site checkout.
+      - name: copy the docs into the site
+        working-directory: site
+        env:
+          PROJECT: ${{ inputs.project }}
+        run: jbang tools/docs/Docs.java sync --strict --project "$PROJECT" --version main --source ../project
+
+      - name: render the site
+        working-directory: site
+        env:
+          QUARKUS_ROQ_GENERATOR_BATCH: 'true'
+        run: |
+          ./mvnw -B -q package quarkus:run -DskipTests 2>&1 | tee ../render.log
+          # Asciidoctor warnings (such as a section level out of sequence) are reported; a page that
+          # fails to render, or an include that cannot be resolved, fails the check.
+          grep -E 'WARNING \[asciidoctor\]' ../render.log | sed 's/^.*WARNING \[asciidoctor\] ([^)]*) /::warning::/' || true
+          if grep -E 'Roq request failed|Error occurred while rendering|SEVERE \[asciidoctor\]' ../render.log; then
+            echo "::error::The documentation does not render cleanly, see the lines above"
+            exit 1
+          fi
+
+      - name: add the pages versions share
+        working-directory: site
+        run: jbang tools/docs/Docs.java inherit target/roq
+
+      - name: add redirects for moved documentation
+        working-directory: site
+        run: jbang tools/docs/Docs.java redirects target/roq
+
+      # A link to a page that is not in the site fails the check.
+      - name: check the links between pages
+        working-directory: site
+        run: jbang tools/docs/Docs.java links target/roq
+
+      - name: attach the rendered docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-${{ inputs.project }}
+          path: site/target/roq
+          retention-days: 7

.github/workflows/docs-sync.yml

@@ -0,0 +1,101 @@
+name: Sync project documentation
+
+# Pulls each project's AsciiDoc documentation (data/docs.yml) into content/docs/ and commits it to
+# develop, which then builds and deploys the site. Nightly it picks up new commits on the projects'
+# main branches and new release tags; it can also be run by hand for one project or one version.
+
+on:
+  schedule:
+    - cron: "30 4 * * *"
+  workflow_dispatch:
+    inputs:
+      project:
+        description: 'Project key from data/docs.yml (empty: all projects)'
+        required: false
+      version:
+        description: 'Version id (main, latest, a minor such as 2.9, a stream id); with ref, syncs exactly that'
+        required: false
+      ref:
+        description: 'Branch or tag to sync the version from'
+        required: false
+      force:
+        description: 'Sync even when nothing changed upstream'
+        type: boolean
+        default: false
+
+concurrency:
+  group: docs-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    if: github.repository_owner == 'smallrye'
+    runs-on: ubuntu-latest
+    # Diagram blocks ([mermaid], [plantuml], ...) are rendered to SVG by the sync (tools/docs/Docs.java).
+    services:
+      kroki:
+        image: yuzutech/kroki
+        env:
+          KROKI_MERMAID_HOST: kroki-mermaid
+        ports:
+          - 8000:8000
+      kroki-mermaid:
+        image: yuzutech/kroki-mermaid
+    env:
+      KROKI_URL: http://localhost:8000
+    steps:
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.CI_APP_ID }}
+          private-key: ${{ secrets.CI_APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@v4
+        with:
+          ref: develop
+          # A push made with the app token (not GITHUB_TOKEN) starts the website build.
+          token: ${{ steps.app-token.outputs.token }}
+
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - uses: jbangdev/setup-jbang@2b1b465a7b75f4222b81426f23a01e013aa7b95c # v0.1.1
+        with:
+          version: 0.138.0
+
+      # Releases still documented with MkDocs are converted with pandoc.
+      - name: install pandoc
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq pandoc
+
+      - name: sync
+        env:
+          PROJECT: ${{ inputs.project }}
+          VERSION: ${{ inputs.version }}
+          REF: ${{ inputs.ref }}
+          FORCE: ${{ inputs.force }}
+        run: |
+          if [ -n "$VERSION" ] && [ -n "$REF" ]; then
+            args=(--project "$PROJECT" --version "$VERSION" --ref "$REF")
+          else
+            args=(--auto)
+            [ -n "$PROJECT" ] && args+=(--project "$PROJECT")
+            [ "$FORCE" = true ] && args+=(--force)
+          fi
+          jbang tools/docs/Docs.java sync "${args[@]}" --summary "$GITHUB_STEP_SUMMARY"
+
+      - name: commit
+        run: |
+          git add -A content/docs data/docversions.yml
+          if git diff --cached --quiet; then
+            echo "Documentation unchanged"
+            exit 0
+          fi
+          slug='${{ steps.app-token.outputs.app-slug }}'
+          git config user.name "$slug[bot]"
+          git config user.email "$(gh api "/users/$slug%5Bbot%5D" --jq .id)+$slug[bot]@users.noreply.github.com"
+          git commit -q -m "Sync project documentation"
+          git push origin develop
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}

.gitignore

@@ -6,3 +6,4 @@ package-lock.json
 .idea
 .vscode
 .quarkus
+__pycache__/