PR builds include a live preview (Qiskit#55)

Closes Qiskit#3. We use the same open
source workflow we use with qiskit.org and qiskit-sphinx-theme.

We only preview the docs for PRs built directly on this repository, not
for forks. That is a security restriction due to how forks work.

Author: Eric-Arellano

.github/workflows/preview-docs.yaml

@@ -0,0 +1,37 @@
+# This Action builds the docs in pull requests so that we can view a live preview.
+# It uses IBM Cloud to build the Dockerfile at the root of the repository.
+#
+# Due to security, this can only run on branches of qiskit/docs, i.e. not on forks.
+# We skip the actions if running on a fork.
+
+name: Preview
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+
+jobs:
+  setup:
+    if: |
+      (github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'synchronize') &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    uses: Qiskit/gh-actions/.github/workflows/code-engine-preview.yml@main
+    with:
+      code_engine_project: qiskit-docs-preview
+      docker_image_name: qiskit-docs-preview
+      docker_image_port: "3000"
+    secrets:
+      ibmcloud_account: ${{ secrets.IBMCLOUD_ACCOUNT }}
+      ibmcloud_api_key: ${{ secrets.IBMCLOUD_API_KEY }}
+
+  teardown:
+    if: |
+      github.event.action == 'closed' &&
+      github.event.pull_request.head.repo.full_name == github.repository
+    uses: Qiskit/gh-actions/.github/workflows/code-engine-cleanup.yml@main
+    with:
+      code_engine_project: qiskit-docs-preview
+      docker_image_name: qiskit-docs-preview
+    secrets:
+      ibmcloud_account: ${{ secrets.IBMCLOUD_ACCOUNT }}
+      ibmcloud_api_key: ${{ secrets.IBMCLOUD_API_KEY }}

Dockerfile

@@ -0,0 +1,30 @@
+# This code is a Qiskit project.
+#
+# (C) Copyright IBM 2023.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# This Dockerfile is used to preview the docs in pull requests via GitHub Actions.
+#
+# Keep it in sync with ./start. This Dockerfile essentially is the same,
+# only it sets the CLI args directly in the Dockerfile because the
+# GitHub Action expects that.
+#
+# To test it out locally:
+#
+#   1. ❯ docker build -t qiskit-docs-preview .
+#   2. ❯ docker run --rm -p 3000:3000 -t qiskit-docs-preview
+#   3. Open up http://localhost:3000
+
+FROM icr.io/quantum-computing/iqp-channel-docs-dev
+
+COPY docs/ /home/node/app/docs
+COPY public/images /home/node/app/public/images
+
+EXPOSE 3000 5001

README.md

@@ -33,6 +33,12 @@ npm install
 
 Run `./start` in your terminal, then open http://localhost:3000 in your browser.
 
+## Preview the docs in PRs
+
+Contributors with write access to this repository can use live previews of the docs: GitHub will deploy a website using your changes.
+
+To use live previews, push your branch to `upstream` rather than your fork. GitHub will leave a comment with the link to the site. Please prefix your branch name with your initials, e.g. `EA/fix-build-typo`, for good Git hygiene.
+
 ## Spellcheck
 
 We use [cSpell](https://cspell.org) to check for spelling. The `lint` job in CI will fail if there are spelling issues.

start

@@ -11,6 +11,7 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
+# Keep this in sync with the Dockerfile at the root of the repository.
 docker run \
   -v "$(pwd)"/docs:/home/node/app/docs \
   -v "$(pwd)"/public/images:/home/node/app/public/images \