Migrate documentation from Doxygen to Antora + MrDocs

.github/workflows/ci_tests.yml

@@ -16,10 +16,10 @@ on:
 
 jobs:
   beman-submodule-check:
-    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-submodule-check.yml@503ac65da3fd803044bc82b2fe748b2fc6f503cd # 1.5.3
+    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-submodule-check.yml@4d946e210ce2ee68ccd8607c8acccacf171830c5 # 1.7.1
 
   preset-test:
-    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-preset-test.yml@503ac65da3fd803044bc82b2fe748b2fc6f503cd # 1.5.3
+    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-preset-test.yml@4d946e210ce2ee68ccd8607c8acccacf171830c5 # 1.7.1
     with:
       matrix_config: >
         [
@@ -34,7 +34,7 @@ jobs:
         ]
 
   build-and-test:
-    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-build-and-test.yml@503ac65da3fd803044bc82b2fe748b2fc6f503cd # 1.5.3
+    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-build-and-test.yml@4d946e210ce2ee68ccd8607c8acccacf171830c5 # 1.7.1
     with:
       matrix_config: >
         {
@@ -147,4 +147,4 @@ jobs:
     permissions:
       contents: read
       issues: write
-    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-create-issue-when-fault.yml@503ac65da3fd803044bc82b2fe748b2fc6f503cd # 1.5.3
+    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-create-issue-when-fault.yml@4d946e210ce2ee68ccd8607c8acccacf171830c5 # 1.7.1

.github/workflows/codeql.yml

@@ -59,7 +59,7 @@ jobs:
             # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -77,7 +77,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
+        uses: github/codeql-action/init@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
@@ -106,7 +106,7 @@ jobs:
 
           exit 1
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
+        uses: github/codeql-action/analyze@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
         with:
 
           category: "/language:${{matrix.language}}"

.github/workflows/docs.yml

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+
+name: Documentation
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write       # needed for gh-pages deploy on main
+      pull-requests: write  # needed to post the preview comment on PRs
+
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          fetch-depth: 1
+
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: '20'
+
+      - name: Install Clang
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y clang-18 libclang-18-dev
+
+      - name: Cache MrDocs
+        uses: actions/cache@v4
+        with:
+          path: .tools/mrdocs
+          key: mrdocs-${{ runner.os }}-${{ hashFiles('etc/install-mrdocs.sh') }}
+
+      - name: Cache node_modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: npm-${{ hashFiles('package-lock.json') }}
+
+      - name: Build documentation
+        run: make docs
+
+      - name: Locate output directory
+        id: out
+        run: echo "dir=$(make -s print-docs-out)" >> "$GITHUB_OUTPUT"
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: ${{ steps.out.outputs.dir }}/
+          retention-days: 14
+
+      # Posts a comment on the PR with a direct link to the workflow run
+      # where the docs-site artifact can be downloaded and inspected.
+      # Uses a hidden marker so the comment is updated (not duplicated) on
+      # each push to the PR branch.
+      # continue-on-error because fork PRs may lack write permission for
+      # pull-requests; the build still passes even if the comment fails.
+      - name: Post or update PR preview comment
+        if: github.event_name == 'pull_request'
+        continue-on-error: true
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const MARKER = '<!-- docs-preview-comment -->'
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
+            const sha = context.payload.pull_request.head.sha.slice(0, 7)
+            const body = [
+              MARKER,
+              `📚 **Documentation preview** for \`${sha}\` — [workflow run](${runUrl})`,
+              '',
+              'To review: open the **docs-site** artifact from that run,',
+              'extract the zip, and open `index.html` in a browser.',
+            ].join('\n')
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            })
+            const existing = comments.find(c => c.body.includes(MARKER))
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              })
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              })
+            }
+
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ${{ steps.out.outputs.dir }}
+          publish_branch: gh-pages

.github/workflows/ossf-scorecard-analysis.yml

@@ -22,7 +22,7 @@ jobs:
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -56,6 +56,6 @@ jobs:
       # Upload the results to GitHub's code scanning dashboard (optional).
       # Commenting out will disable upload of results to your repo's Code Scanning dashboard
       - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@95e58e9a2cdfd71adc6e0353d5c52f41a045d225 # v4.35.2
+        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
         with:
           sarif_file: results.sarif

.github/workflows/pre-commit-check.yml

@@ -15,4 +15,4 @@ jobs:
       checks: write
       issues: write
       pull-requests: write
-    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-pre-commit.yml@503ac65da3fd803044bc82b2fe748b2fc6f503cd # ratchet:bemanproject/infra-workflows/.github/workflows/reusable-beman-pre-commit.yml@1.5.3
+    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-pre-commit.yml@4d946e210ce2ee68ccd8607c8acccacf171830c5 # ratchet:bemanproject/infra-workflows/.github/workflows/reusable-beman-pre-commit.yml@1.7.1

.github/workflows/pre-commit-update.yml

@@ -15,7 +15,7 @@ jobs:
     permissions:
       contents: write
       pull-requests: write
-    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-update-pre-commit.yml@503ac65da3fd803044bc82b2fe748b2fc6f503cd # 1.5.3
+    uses: bemanproject/infra-workflows/.github/workflows/reusable-beman-update-pre-commit.yml@4d946e210ce2ee68ccd8607c8acccacf171830c5 # 1.7.1
     secrets:
       APP_ID: ${{ secrets.AUTO_PR_BOT_APP_ID }}
       PRIVATE_KEY: ${{ secrets.AUTO_PR_BOT_PRIVATE_KEY }}

.github/workflows/pre-commit.yml

@@ -19,7 +19,7 @@ jobs:
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 
@@ -50,7 +50,7 @@ jobs:
 
     steps:
       - name: Harden the runner (Audit all outbound calls)
-        uses: step-security/harden-runner@8d3c67de8e2fe68ef647c8db1e6a09f647780f40 # v2.19.0
+        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
         with:
           egress-policy: audit
 

.gitignore

@@ -32,6 +32,8 @@ compile_commands.json
 /docs/html
 /docs/latex
 /docs/adoc/
+/docs/modules/ROOT/pages/reference/
+/node_modules/
 /build/
 /installtest/.build/
 

.pre-commit-config.yaml

@@ -42,14 +42,15 @@ repos:
         args: ['-I', '.codespell_ignore', '--uri-ignore-words-list', '*']
         exclude: >
           (?x)^(
-            papers/.*
+            papers/.* |
+            package-lock.json
           )$
 
-    # Beman Standard checking via beman-tidy
-  - repo: https://github.com/bemanproject/beman-tidy
-    rev: v0.4.0
-    hooks:
-    - id: beman-tidy
-      args: [".", "--verbose", "--require-all"]
+#    # Beman Standard checking via beman-tidy
+#  - repo: https://github.com/bemanproject/beman-tidy
+#    rev: v0.4.0
+#    hooks:
+#    - id: beman-tidy
+#      args: [".", "--verbose", "--require-all"]
 
 exclude: 'infra/'