diff --git a/.github/workflows/docs-generate-html.yml b/.github/workflows/docs-generate-html.yml
index 3380503..bf511a0 100644
--- a/.github/workflows/docs-generate-html.yml
+++ b/.github/workflows/docs-generate-html.yml
@@ -1,56 +1,49 @@
-
name: "Generate HTML"
+run-name: "Generate ${{ inputs.publish-env }} HTML from ${{ github.ref_name }}"
+
+permissions:
+ contents: read
-# edit the list of branches according to your repository
-# the list of branches should contain all the branches in your Antora publish playbooks
+# Builds, verifies, and publishes docs for ONE environment, as a run entirely independent
+# of any other environment's run. Triggered (via the API, not a workflow_call) by
+# docs-trigger-builds.yml, once per environment that applies to a given push (dev, prod, or both) -
+# so if dev's run fails, prod's run is completely unaffected, and vice versa.
+#
+# No build-ref input: the git ref to build from is always whatever ref this run was
+# itself dispatched against (the "Use workflow from" branch when triggered manually, or
+# docs-trigger-builds.yml's own `ref:` when triggered automatically - which it always sets
+# to the same value it also used to pass as a build-ref input here, so that separate input
+# never actually carried any information github.ref_name didn't already have). Reading
+# github.ref_name directly instead removes a second, redundant "which branch" box from
+# manual dispatch.
+#
+# Do not run this by hand. It has a workflow_dispatch trigger only because the API call that
+# starts it needs one, and it must run as its own run so that its head_branch is the branch
+# being built (which docs-publish checks), so it cannot be a workflow_call either. To build
+# now, run docs-trigger-builds.yml from the branch instead; it works out the environments the
+# same way it does for a push. publish-env is always set by the trigger, so there is nothing
+# to derive from the branch here.
on:
- push:
- branches:
- - 'main'
workflow_dispatch:
-
-# change `dev` and `main` according to your repository's branch names
-# `dev` is the branch you use to build and publish to staging
-# `main` is the branch you use to build and publish to neo4j.com/docs
-# in some cases, PROD_BRANCH and DEV_BRANCH may be the same branch
-env:
- DEV_BRANCH: 'main'
- PROD_BRANCH: 'main'
+ inputs:
+ publish-env:
+ description: "The environment to publish to"
+ type: choice
+ required: true
+ options:
+ - dev
+ - prod
jobs:
- prepare-ref-env:
- name: Set build branch and environments
- runs-on: ubuntu-latest
- outputs:
- build-ref: ${{ steps.set-ref-env.outputs.build-ref }}
- environments: ${{ steps.set-ref-env.outputs.environments }}
- steps:
- - name: Set Build Ref
- id: set-ref-env
- run: |
- if [[ "${GITHUB_REF}" == "refs/heads/${{ env.DEV_BRANCH }}" ]]; then
- build_from=${{ env.DEV_BRANCH }}
- environments='["dev"]'
- else
- build_from=${{ env.PROD_BRANCH }}
- environments='["prod"]'
- fi
- # if dev branch = prod branch publish to both
- if [[ "${{ env.DEV_BRANCH }}" == "${{ env.PROD_BRANCH }}" ]]; then
- environments='["dev","prod"]'
- fi
- echo "build-ref=${build_from}" >> $GITHUB_OUTPUT
- echo "environments=${environments[@]}" >> $GITHUB_OUTPUT
-
docs-build:
name: Generate HTML
- needs: prepare-ref-env
uses: neo4j/docs-tools/.github/workflows/reusable-docs-build.yml@v2
with:
package-script: 'verify:publish'
- build-ref: ${{needs.prepare-ref-env.outputs.build-ref}}
+ build-ref: ${{ github.ref_name }}
fetch-depth: 0
+ publish-env: ${{ inputs.publish-env }}
docs-verify:
name: Verify HTML
@@ -59,17 +52,14 @@ jobs:
with:
failOnWarnings: true
+ # Hand off to docs-publish (a separate repo) to actually publish this run's "docs"
+ # artifact.
publish-html:
name: Publish HTML
- needs: [docs-verify, prepare-ref-env]
+ needs: docs-verify
runs-on: ubuntu-latest
-
- strategy:
- matrix:
- environments: ${{ fromJson(needs.prepare-ref-env.outputs.environments) }}
-
steps:
- - name: Publish to ${{ matrix.environments }}
+ - name: Publish to ${{ inputs.publish-env }}
uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 #v4
with:
token: ${{ secrets.DOCS_DISPATCH_TOKEN }}
@@ -80,10 +70,5 @@ jobs:
"org": "${{ github.repository_owner }}",
"repo": "${{ github.event.repository.name }}",
"run_id": "${{ github.run_id }}",
- "publish_env": "${{ matrix.environments }}"
+ "publish_env": "${{ inputs.publish-env }}"
}
-
- - name: Echo
- if: ${{ matrix.environments == 'prod' }}
- run: |
- echo "If this step runs then approval has been granted" >> $GITHUB_STEP_SUMMARY
diff --git a/.github/workflows/docs-generate-pdf.yml b/.github/workflows/docs-generate-pdf.yml
new file mode 100644
index 0000000..e32359e
--- /dev/null
+++ b/.github/workflows/docs-generate-pdf.yml
@@ -0,0 +1,68 @@
+name: "Generate PDF"
+run-name: "Generate ${{ inputs.publish-env }} PDF from ${{ github.ref_name }}"
+
+permissions:
+ contents: read
+
+# Mirrors docs-generate-html.yml's shape (workflow_dispatch with a publish-env input,
+# build -> publish) and its own reusable-workflow reference convention (a
+# pinned neo4j/docs-tools/...@v2 tag, not a relative path - this repo doesn't contain
+# reusable-docs-pdf-build.yml itself). Still simpler than docs-generate-html.yml in one
+# way: there's no docs-verify step (no equivalent check exists yet for a PDF), and
+# build/publish are two plain jobs rather than a reusable-workflow call plus a verify call.
+#
+# No build-ref input - see docs-generate-html.yml's own comment on why: the git ref to
+# build from is always whatever ref this run was itself dispatched against.
+#
+# Do not run this by hand. It has a workflow_dispatch trigger only because the API call that
+# starts it needs one, and it must run as its own run so that its head_branch is the branch
+# being built (which docs-publish checks), so it cannot be a workflow_call either. To build
+# now, run docs-trigger-builds.yml from the branch instead; it works out the environments the
+# same way it does for a push. publish-env is always set by the trigger, so there is nothing
+# to derive from the branch here.
+on:
+ workflow_dispatch:
+ inputs:
+ publish-env:
+ description: "The environment to publish to"
+ type: choice
+ required: true
+ options:
+ - dev
+ - prod
+
+jobs:
+
+ docs-build-pdf:
+ name: Generate PDF
+ uses: neo4j/docs-tools/.github/workflows/reusable-docs-pdf-build.yml@v2
+ with:
+ build-ref: ${{ github.ref_name }}
+ fetch-depth: 0
+ publish-env: ${{ inputs.publish-env }}
+
+ # Hand off to docs-publish (a separate repo) to actually publish this run's "pdf"
+ # artifact - same mechanism docs-generate-html.yml already uses for its "docs"
+ # artifact. docset/version come from docs-build-pdf itself (read back out of the
+ # PDF's own build path - see reusable-docs-pdf-build.yml), since there's no HTML
+ # directory tree here for docs-publish to infer them from the way it does for HTML.
+ publish-pdf:
+ name: Publish PDF
+ needs: docs-build-pdf
+ runs-on: ubuntu-latest
+ steps:
+ - name: Publish to ${{ inputs.publish-env }}
+ uses: peter-evans/repository-dispatch@28959ce8df70de7be546dd1250a005dd32156697 #v4
+ with:
+ token: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+ repository: neo4j/docs-publish
+ event-type: publish-pdf
+ client-payload: |-
+ {
+ "org": "${{ github.repository_owner }}",
+ "repo": "${{ github.event.repository.name }}",
+ "run_id": "${{ github.run_id }}",
+ "publish_env": "${{ inputs.publish-env }}",
+ "docset": "${{ needs.docs-build-pdf.outputs.docset }}",
+ "version": "${{ needs.docs-build-pdf.outputs.version }}"
+ }
diff --git a/.github/workflows/docs-trigger-builds.yml b/.github/workflows/docs-trigger-builds.yml
new file mode 100644
index 0000000..5f34e84
--- /dev/null
+++ b/.github/workflows/docs-trigger-builds.yml
@@ -0,0 +1,31 @@
+name: "Trigger docs builds"
+
+# Dispatches output generation builds. The reusable workflow determines which builds are
+# triggered, the branch that each build runs on, and the environment (prod or dev) that the
+# build generates output for.
+
+permissions:
+ contents: read
+ actions: write
+
+# List all the branches that contain publishable docs.
+on:
+ push:
+ branches:
+ - 'main'
+ workflow_dispatch:
+
+jobs:
+ trigger:
+ name: Trigger builds
+ uses: neo4j/docs-tools/.github/workflows/reusable-docs-trigger-builds.yml@v2
+ # Inputs you can add:
+ # with:
+ # # docs-dir: the path in the repo that contains the documentation source. You only need
+ # # to provide a value if the source is not in the repo root.
+ # docs-dir: docs
+ # # pdf: false: by default a PDF build is always triggered. Add this if you do not want to
+ # # generate a PDF for this project.
+ # pdf: false
+ secrets:
+ DOCS_DISPATCH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}