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 }}