Docs workflows

.github/workflows/docs-deploy-surge.yml

@@ -0,0 +1,124 @@
+# Use this starter workflow to deploy HTML generated by Antora to surge.sh
+# Docs are published at <org>-<repo>-<deployid>.surge.sh
+#
+# By default, this workflow runs on completion of a workflow called "Verify docs PR"
+#
+# This workflow expects the triggering workflow to generate an artifact called "docs"
+# - update the reference to "docs" and "docs.zip" in this workflow if your triggering workflow generates an artifact with a different name
+
+# change to force workflow with no changelog
+
+name: "Deploy docs preview"
+
+on:
+  workflow_run:
+    workflows: ["Verify docs PR"]
+    types:
+      - completed
+
+jobs:
+  deploy-docs:
+    # Uncomment this if statement to deploy only when the PR builds cleanly
+    # if: github.event.workflow_run.conclusion == 'success'
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Download built documentation"
+        uses: actions/github-script@v7
+        env:
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          WORKSPACE: ${{ github.workspace }}
+        with:
+          script: |
+            var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               run_id: ${{ env.RUN_ID }},
+            });
+
+            var matchArtifactDocs = artifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "docs"
+            })[0];
+            var downloadDocs = await github.rest.actions.downloadArtifact({
+               owner: context.repo.owner,
+               repo: context.repo.repo,
+               artifact_id: matchArtifactDocs.id,
+               archive_format: 'zip',
+            });
+            var fs = require('fs');
+            fs.writeFileSync('${{ env.WORKSPACE }}/docs.zip', Buffer.from(downloadDocs.data));
+
+            var matchArtifactChangelog = artifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "changelog"
+            })[0];
+            var downloadChangelog = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: matchArtifactChangelog.id,
+              archive_format: 'zip',
+            });
+            fs.writeFileSync('${{ env.WORKSPACE }}/changelog.zip', Buffer.from(downloadChangelog.data));
+
+      - id: unzip-docs
+        run: unzip docs.zip
+
+      - id: unzip-changelog
+        if: ${{ hashFiles('changelog.zip') != '' }}
+        run: unzip changelog.zip
+
+      - id: get-deploy-id
+        run: |
+          deployid=$(<deployid)
+          case "$deployid" in ''|*[!0-9]*) echo "Provided PR number is not an integer"; exit 1 ;; esac
+          echo "deploy-id=$deployid" >> "$GITHUB_OUTPUT"
+
+      - id: get-deploy-url
+        env:
+          ORG: ${{ github.event.repository.owner.login }}
+          REPO: ${{ github.event.repository.name }}
+          DEPLOYID: ${{ steps.get-deploy-id.outputs.deploy-id }}
+        run: |
+          deployurl=$ORG-$REPO-$DEPLOYID.surge.sh
+          echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+
+      - name: Deploy docs to surge
+        shell: bash
+        env:
+          DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }}
+          SURGE_TOKEN: "${{ secrets.DOCS_SURGE_TOKEN }}"
+          SITE_DIR: ${{ steps.get-top-dir.outputs.top-dir }}
+        run: |
+          npm install -g surge
+          surge . $DEPLOY_URL --token "$SURGE_TOKEN"
+
+      # If the PR artifacts include a changelog file, add it to the PR as a comment
+      # The changelog contains links to new and changed files in the deployed docs
+      - name: Comment on PR (changelog)
+        if: ${{ hashFiles('changelog') != '' }}
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 #v2
+        with:
+          number: ${{ steps.get-deploy-id.outputs.deploy-id }}
+          recreate: true
+          header: docs-pr-changes
+          path: changelog
+          GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }}
+
+      # If there's no changelog, add a generic comment to the PR
+      - name: Comment on PR (no changelog)
+        if: ${{ hashFiles('changelog') == '' }}
+        env:
+          DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }}
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 #v2
+        with:
+          number: ${{ steps.get-deploy-id.outputs.deploy-id }}
+          header: docs-pr-changes
+          message: |
+            Looks like you've updated the documentation!
+
+            Check out your changes at https://${{ env.DEPLOY_URL }}
+          GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }}

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

@@ -0,0 +1,59 @@
+name: "Verify docs PR"
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "doc/**"
+
+jobs:
+  #  Generate HTML
+  docs-build-pr:
+    uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2
+    with:
+      deploy-id: ${{ github.event.number }}
+      retain-artifacts: 14
+      docs-dir: "doc"
+
+  # 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
+    with:
+      failOnWarnings: true
+
+  # Get lists of changes in the PR
+  # - all updated asciidoc files
+  # - all updated asciidoc pages
+  # - all new asciidoc pages
+  docs-changes-pr:
+    runs-on: ubuntu-latest
+    outputs:
+      asciidoc-files: ${{ steps.get-file-changes.outputs.asciidoc_all_changed_files }}
+      pages-modified: ${{ steps.get-file-changes.outputs.pages_modified_files }}
+      pages-added: ${{ steps.get-file-changes.outputs.pages_added_files }}
+    steps:
+      - name: Get file changes
+        id: get-file-changes
+        uses: tj-actions/changed-files@2f7c5bfce28377bc069a65ba478de0a74aa0ca32 # v46.0.1
+        with:
+          separator: ","
+          files_yaml: |
+            pages:
+            - '**/modules/**/pages/**/*.adoc'
+            asciidoc:
+            - '**/modules/**/*.adoc'
+
+  # Generate a PR comment if the docs are using the pageList extension
+  # The extension maps asciidoc source files to their HTML output paths
+  # The comment will contain links to new and changed pages in the deployed HTML docs
+  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
+    with:
+      pages-modified: ${{ needs.docs-changes-pr.outputs.pages-modified }}
+      pages-added: ${{ needs.docs-changes-pr.outputs.pages-added }}

.github/workflows/docs-teardown.yml

@@ -0,0 +1,49 @@
+#  copy this workflow into your repo
+name: "Documentation Teardown"
+
+on:
+  pull_request_target:
+    branches:
+      - main
+    types:
+      - closed
+    paths:
+      - "doc/**"
+
+jobs:
+  teardown-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+
+      - id: get-deploy-url
+        env:
+          ORG: ${{ github.event.repository.owner.login }}
+          REPO: ${{ github.event.repository.name }}
+          DEPLOYID: ${{ github.event.pull_request.number }}
+        run: |
+          deployurl=$ORG-$REPO-$DEPLOYID.surge.sh
+          echo "deploy-url=$deployurl" >> $GITHUB_OUTPUT
+
+      - name: Teardown documentation
+        shell: bash
+        env:
+          SURGE_TOKEN: "${{ secrets.DOCS_SURGE_TOKEN }}"
+          DEPLOY_URL: ${{ steps.get-deploy-url.outputs.deploy-url }}
+        run: |
+          npm install -g surge
+          surge teardown $DEPLOY_URL --token "$SURGE_TOKEN"
+
+      - name: Comment on PR
+        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 #v2
+        with:
+          number: ${{ github.event.pull_request.number }}
+          header: docs-pr-changes
+          message: |
+            Thanks for the documentation updates.
+
+            The preview documentation has now been torn down - reopening this PR will republish it.
+          GITHUB_TOKEN: ${{ secrets.DOCS_PR_COMMENT_TOKEN }}

doc/modules/ROOT/pages/graph-object.adoc

@@ -86,7 +86,7 @@ Cypher projection is not a dedicated procedure; rather it requires writing a Cyp
 
 Read more about Cypher projection in the https://neo4j.com/docs/graph-data-science/current/management-ops/projections/graph-project-cypher-projection/[GDS manual].
 
-The method `gds.graph.cypher.project` bridges the gap between <<getting-started-minimal-example, `gds.run_cypher`>> and having to follow with `gds.graph.get`.
+The method `gds.graph.cypher.project` bridges the gap between xref:getting-started.adoc#getting-started-minimal-example[`gds.run_cypher`] and having to follow with `gds.graph.get`.
 
 === Syntax
 .Cypher projection signature

doc/modules/ROOT/pages/pipelines.adoc

@@ -42,11 +42,11 @@ Below is a description of the methods on such objects:
                             Union[str, list[str]]       | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-adding-features[Select node properties to be used as features].
 | configureSplit        | config: **kwargs              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-configure-splits[Configure the train-test dataset split].
 | addLogisticRegression | parameter_space: +
-                            dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-adding-model-candidates[Add a logistic regression model configuration to train as a candidate in the model selection phase]. footnote:range[Ranges can also be given as length two `Tuple`s. I.e. `(x, y)` is the same as `{range: [x, y]}`.]
+                            dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-adding-model-candidates[Add a logistic regression model configuration to train as a candidate in the model selection phase]. footnote:classification-range[Ranges can also be given as length two ``Tuple``s. I.e. `(x, y)` is the same as `{range: [x, y\]}`.]
 | addRandomForest       | parameter_space: +
-                            dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-adding-model-candidates[Add a random forest model configuration to train as a candidate in the model selection phase]. footnote:range[]
+                            dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-adding-model-candidates[Add a random forest model configuration to train as a candidate in the model selection phase]. footnote:classification-range[]
 | addMLP                | parameter_space: +
-                            dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-adding-model-candidates[Add an MLP model configuration to train as a candidate in the model selection phase]. footnote:range[]
+                            dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-adding-model-candidates[Add an MLP model configuration to train as a candidate in the model selection phase]. footnote:classification-range[]
 | configureAutoTuning   | config: **kwargs
                                                         | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/nodeclassification-pipelines/config/#nodeclassification-pipelines-configure-auto-tuning[Configure the auto-tuning].
 | train                 | G: Graph, +
@@ -221,11 +221,11 @@ Below is a description of the methods on such objects:
                         config: **kwargs                | Series              | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-adding-features[Add a link feature for model training based on node properties and a feature combiner].
 | configureSplit        | config: **kwargs              | Series              | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-configure-splits[Configure the feature-train-test dataset split].
 | addLogisticRegression | parameter_space: +
-                          dict[str, any]                | Series              | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-adding-model-candidates[Add a logistic regression model configuration to train as a candidate in the model selection phase]. footnote:range[Ranges can also be given as length two `Tuple`s. I.e. `(x, y)` is the same as `{range: [x, y]}`.]
+                          dict[str, any]                | Series              | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-adding-model-candidates[Add a logistic regression model configuration to train as a candidate in the model selection phase]. footnote:prediction-range[Ranges can also be given as length two ``Tuple``s. I.e. `(x, y)` is the same as `{range: [x, y\]}`.]
 | addRandomForest       | parameter_space: +
-                          dict[str, any]                | Series              | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-adding-model-candidates[Add a random forest model configuration to train as a candidate in the model selection phase]. footnote:range[]
+                          dict[str, any]                | Series              | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-adding-model-candidates[Add a random forest model configuration to train as a candidate in the model selection phase]. footnote:prediction-range[]
 | addMLP                | parameter_space: +
-                          dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-adding-model-candidates[Add an MLP model configuration to train as a candidate in the model selection phase]. footnote:range[]
+                          dict[str, any]              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-adding-model-candidates[Add an MLP model configuration to train as a candidate in the model selection phase]. footnote:prediction-range[]
 | configureAutoTuning   | config: **kwargs
                                                         | Series              | https://neo4j.com/docs/graph-data-science/current/machine-learning/linkprediction-pipelines/config/#linkprediction-configure-auto-tuning[Configure the auto-tuning].
 | train                 | G: Graph, +
@@ -395,9 +395,9 @@ config: **kwargs        | Series                        | https://neo4j.com/docs
 Union[str, list[str]]   | Series                        | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/noderegression-pipelines/config/#noderegression-pipelines-adding-features[Select node properties to be used as features].
 | configureSplit        | config: **kwargs              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/noderegression-pipelines/config/#noderegression-pipelines-configure-splits[Configure the train-test dataset split].
 | addLinearRegression   | parameter_space: +
-dict[str, any]          | Series                        | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/noderegression-pipelines/config/#noderegression-pipelines-adding-model-candidates[Add a linear regression model configuration to train as a candidate in the model selection phase]. footnote:range[Ranges can also be given as length two `Tuple`s. I.e. `(x, y)` is the same as `{range: [x, y]}`.]
+dict[str, any]          | Series                        | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/noderegression-pipelines/config/#noderegression-pipelines-adding-model-candidates[Add a linear regression model configuration to train as a candidate in the model selection phase]. footnote:regression-range[Ranges can also be given as length two ``Tuple``s. I.e. `(x, y)` is the same as `{range: [x, y\]}`.]
 | addRandomForest       | parameter_space: +
-dict[str, any]          | Series                        | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/noderegression-pipelines/config/#noderegression-pipelines-adding-model-candidates[Add a random forest model configuration to train as a candidate in the model selection phase]. footnote:range[]
+dict[str, any]          | Series                        | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/noderegression-pipelines/config/#noderegression-pipelines-adding-model-candidates[Add a random forest model configuration to train as a candidate in the model selection phase]. footnote:regression-range[]
 | configureAutoTuning   | config: **kwargs              | Series                  | https://neo4j.com/docs/graph-data-science/current/machine-learning/node-property-prediction/noderegression-pipelines/config/#noderegression-pipelines-configure-auto-tuning[Configure the auto-tuning].
 | train                 | G: Graph, +
 config: **kwargs        | NCPredictionPipeline, +

doc/modules/ROOT/pages/tutorials/heterogeneous-node-classification-with-hashgnn.adoc

@@ -285,8 +285,8 @@ found was logistic regression with `penalty=0.159748`.
 
 Further we note that the test set F1 score is 0.59118347, which is
 really good to when comparing to scores of other algorithms on this
-dataset in the literature. More on this in the
-link:#Conclusion[Conclusion] section below.
+dataset in the literature.
+For more information, see <<conclusion>>.
 
 == Making new predictions
 
@@ -328,6 +328,7 @@ _ = pipe.drop()
 _ = model.drop()
 ----
 
+[[conclusion]]
 == Conclusion
 
 By using only the GDS library and its client, we were able to train a