Workflows v2 (neo4j#2542) (neo4j#2577)

Updates workflows so the reference to our reusable workflows is using
`v2`. When minor and patch versions are released, the `v2` tag will be
kept up to date so it is always referencing the latest versions of the
workflows.

These are new workflows that require different `scripts` to be defined
in `package.json` so that file has been updated.

There are also changes in `package.json` to improve the nodemon
behavior.

`v2` includes a new link checker to verify links within a docset where
the target includes a fragment (ie xref:page.adoc#section[]`. A warning
is logged if the target section is not found. Ås a result this PR has
some warnings, but they should be resolved by neo4j#2538.

Co-authored-by: Neil Dewhurst <[email protected]>

Author: renetapopova

.github/workflows/docs-branch-checks.yml

@@ -0,0 +1,47 @@
+
+name: "Generate and Publish HTML"
+
+on:
+  push:
+    branches:
+    - 'dev'
+  workflow_dispatch:
+
+env:
+  PUBLISH_TO: ${{ github.ref == 'refs/heads/main' && 'prod' || 'dev' }}
+
+jobs:
+
+  docs-build:
+    name: Generate HTML
+    uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2
+    with:
+      package-script: 'verify:publish'
+
+  docs-verify:
+    name: Verify HTML
+    needs: docs-build
+    uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@v2
+    with:
+      failOnWarnings: true
+
+  publish-html:
+    name: Publish HTML
+    needs: docs-verify
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Trigger Publish
+        uses: peter-evans/repository-dispatch@bf47d102fdb849e755b0b0023ea3e81a44b6f570 # v2.1.2
+        with:
+          token: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+          repository: neo4j/docs-publish
+          event-type: publish-html
+          client-payload: |-
+            {
+              "org": "${{ github.repository_owner }}",
+              "repo": "${{ github.event.repository.name }}",
+              "run_id": "${{ github.run_id }}",
+              "args": "--dryrun",
+              "publish_env": "${{ env.PUBLISH_TO }}"
+            }

.github/workflows/docs-generate-html.yml

@@ -13,18 +13,16 @@ jobs:
 
   #  Generate HTML
   docs-build-pr:
-    uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2.0.0-rc-1
+    uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2
     with:
       deploy-id: ${{ github.event.number }}
-      retain-artifacts: 14
-      antora-extensions-exclude: "@neo4j-antora/xref-hash-validator" # Exclude the xref hash validator extension
 
   # Parse the json log output from the HTML build, and output warnings and errors as annotations
   # Optionally, fail the build if there are warnings or errors
   # By default, the job fails if there are errors, passes if there are warnings only.
   docs-verify-pr:
     needs: docs-build-pr
-    uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@v2.0.0-rc-1
+    uses: neo4j/docs-tools/.github/workflows/reusable-docs-verify.yml@v2
     with:
       failOnWarnings: true
 
@@ -56,7 +54,7 @@ jobs:
   docs-updates-comment-pr:
     if: needs.docs-build-pr.outputs.pages-listed == 'success'
     needs: [docs-build-pr, docs-changes-pr]
-    uses: neo4j/docs-tools/.github/workflows/reusable-docs-pr-changes.yml@v2.0.0-rc-1
+    uses: neo4j/docs-tools/.github/workflows/reusable-docs-pr-changes.yml@v2
     with:
       pages-modified: ${{ needs.docs-changes-pr.outputs.pages-modified }}
       pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }}

.github/workflows/docs-pr-checks.yml

@@ -1,16 +1,20 @@
 {
-  "name": "docs-template",
+  "name": "docs-operations",
   "version": "1.0.0",
-  "description": "Template repo for Neo4j documentation projects",
+  "description": "Neo4j Operations documentation",
   "main": "server.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "start": "npm update && nodemon -e adoc --exec \"npm run build && npm run serve\"",
+    "prestart": "npm update",
+    "start": "nodemon --exec \"npm run build\"",
     "serve": "node server.js",
-    "adoc-gen": "node scripts/adoc-gen.js",
-    "build": "antora preview.yml --stacktrace --log-format=pretty",
-    "build-verify": "antora --stacktrace --fetch preview.yml --log-format=json --log-level=info --log-file ./build/log/log.json",
-    "publish-verify": "antora --stacktrace --fetch publish.yml --log-format=json --log-file ./build/log/log.json"
+    "clean": "rm -rf build",
+    "build": "npm run build:preview",
+    "postbuild": "node server.js",
+    "build:preview": "antora preview.yml --stacktrace --log-format=pretty",
+    "build:publish": "npm run clean && antora publish.yml --stacktrace --log-format=pretty",
+    "verify:preview": "antora --stacktrace --fetch preview.yml --log-format=json --log-level=info --log-file ./build/log/log.json",
+    "verify:publish": "antora --stacktrace --fetch publish.yml --log-format=json --log-level=info --log-file ./build/log/log.json"
   },
   "keywords": [
     "antora",
@@ -19,23 +23,31 @@
   "author": "Neo4j",
   "license": "ISC",
   "dependencies": {
-    "@antora/cli": "^3.1.7",
-    "@antora/site-generator-default": "^3.1.7",
-    "@neo4j-antora/antora-add-notes": "^0.3.1",
+    "antora": "^3.1.10",
+    "@neo4j-antora/antora-add-notes": "^0.3.2",
     "@neo4j-antora/antora-page-roles": "^0.3.2",
-    "@neo4j-antora/antora-table-footnotes": "^0.3.2",
     "@neo4j-antora/antora-unlisted-pages": "^0.1.0",
-    "@neo4j-antora/roles-labels": "^0.1.0-beta.2",
-    "@neo4j-documentation/macros": "^1.0.2",
+    "@neo4j-antora/roles-labels": "^0.1.1",
+    "@neo4j-antora/table-footnotes": "^1.0.0",
+    "@neo4j-antora/xref-hash-validator": "^0.1.3",
+    "@neo4j-documentation/macros": "^1.0.4",
     "@neo4j-documentation/remote-include": "^1.0.0"
   },
   "devDependencies": {
     "express": "^5.1.0",
     "nodemon": "^3.1.0"
   },
-  "overrides": {
-    "@antora/site-generator-default": {
-      "glob-parent": "6.0.2"
-    }
+    "nodemonConfig": {
+    "watch": [
+      "**/modules/**",
+      "**/antora.yml",
+      "**/preview.yml",
+      "**/publish.yml"
+    ],
+    "ext": "yml,yaml,adoc,svg,png,jpg",
+    "ignore": [
+      "build",
+      "node_modules"
+    ]
   }
 }

package.json

@@ -24,16 +24,17 @@ urls:
 
 antora:
   extensions:
-  - require: "@neo4j-antora/antora-unlisted-pages"
+  - "@neo4j-antora/antora-unlisted-pages"
   - "@neo4j-antora/roles-labels"
+  - "@neo4j-antora/table-footnotes"
+  - "@neo4j-antora/xref-hash-validator"
 
 asciidoc:
   extensions:
   - "@neo4j-documentation/remote-include"
   - "@neo4j-documentation/macros"
   - "@neo4j-antora/antora-add-notes"
   - "@neo4j-antora/antora-page-roles"
-  - "@neo4j-antora/antora-table-footnotes"
   attributes:
     page-theme: docs
     page-type: Docs

preview.yml

@@ -25,16 +25,17 @@ urls:
 
 antora:
   extensions:
-  - require: "@neo4j-antora/antora-unlisted-pages"
+  - "@neo4j-antora/antora-unlisted-pages"
   - "@neo4j-antora/roles-labels"
+  - "@neo4j-antora/table-footnotes"
+  - "@neo4j-antora/xref-hash-validator"
 
 asciidoc:
   extensions:
   - "@neo4j-documentation/remote-include"
   - "@neo4j-documentation/macros"
   - "@neo4j-antora/antora-add-notes"
   - "@neo4j-antora/antora-page-roles"
-  - "@neo4j-antora/antora-table-footnotes"
   attributes:
     page-theme: docs
     page-type: Docs