Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 38 additions & 53 deletions .github/workflows/docs-generate-html.yml
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 }}
Expand All @@ -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
68 changes: 68 additions & 0 deletions .github/workflows/docs-generate-pdf.yml
Original file line number Diff line number Diff line change
@@ -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 }}"
}
31 changes: 31 additions & 0 deletions .github/workflows/docs-trigger-builds.yml
Original file line number Diff line number Diff line change
@@ -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 }}
Loading