From b60547299cdaec5d6c1e90b35b3f0c4a921b09f1 Mon Sep 17 00:00:00 2001 From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> Date: Tue, 23 Jan 2024 01:10:48 +0100 Subject: [PATCH] Deploy docs to GitHub Pages (#1356) ## Summary This PR changes the `docs.yml` and `docs_dev.yml` workflows to deploy the documentation to GitHub Pages to migrate the project away from the qiskit.org domain. More information about the change and a quick guide to set up GitHub pages can be found at: https://github.com/Qiskit/ecosystem/issues/578 Reminder task for maintainers to update the docs link in the About text for the repo on the main page once this change happens and the docs are re-deployed. This will need backporting to stable branches. - [ ] Update About text doc link ## Details The PR adds three new workflows, replacing the ones used to deploy to qiskit.org (`docs.yml` and `docs_dev.yml`). The new workflows replicate the same structure used by the old workflows when the documentation was pushed to qiskit.org using the `rclone` command. The documentation will be deployed into the `gh-pages` branch where we will find the latest release in the root of the branch. In addition, we will have one folder named `stable/` for all the previous releases and a second one for the dev docs named `dev/`. gh-pages branch structure example: ``` |- unversioned docs |- stable/ |- stable version1/ |- stable docs |- stable version2/ |- stable docs |- dev/ |- dev docs ``` The three new workflows are: **docs_release.yml** (Docs Publish): This workflow allows us to deploy the docs to GitHub pages into the root of the `gh-pages` branch. This will be the unversioned release we will find on the website. **docs_stable.yml** (Stable Docs Publish): This workflow deploys the release we choose into the `stable/` folder. The documentation will be accessible using the `Previous Releases` collapsible menu in the sidebar. **docs_dev.yml** (Dev Docs Publish): Same workflow as `docs_dev.yml` but deploying the documentation to the `dev/` folder in the `gh-pages` branch. The `docs_release.yml` and the `docs_stable.yml` workflows split the current `docs.yml` workflow into two phases. This change is useful to have more control over what versions we want to deploy. With the old workflow, we needed to deploy everything in a specific order to have the latest version as the unversioned one on the website. With the two workflows, we will be able to re-deploy stable versions when necessary. --------- Co-authored-by: Helena Zhang --- .github/workflows/docs_dev.yml | 15 ++++--- .../workflows/{docs.yml => docs_release.yml} | 16 ++++--- .github/workflows/docs_stable.yml | 38 +++++++++++++++++ docs/conf.py | 2 +- tools/deploy_documentation.sh | 39 ------------------ tools/deploy_documentation_dev.sh | 32 -------------- tools/rclone.conf.enc | Bin 304 -> 0 bytes 7 files changed, 59 insertions(+), 83 deletions(-) rename .github/workflows/{docs.yml => docs_release.yml} (61%) create mode 100644 .github/workflows/docs_stable.yml delete mode 100755 tools/deploy_documentation.sh delete mode 100755 tools/deploy_documentation_dev.sh delete mode 100644 tools/rclone.conf.enc diff --git a/.github/workflows/docs_dev.yml b/.github/workflows/docs_dev.yml index 62efff9243..d8b9fece87 100644 --- a/.github/workflows/docs_dev.yml +++ b/.github/workflows/docs_dev.yml @@ -21,9 +21,12 @@ jobs: python -m pip install --upgrade pip pip install -U virtualenv setuptools wheel tox sudo apt-get install graphviz pandoc - - name: Build and publish - env: - encrypted_rclone_key: ${{ secrets.encrypted_rclone_key }} - encrypted_rclone_iv: ${{ secrets.encrypted_rclone_iv }} - run: | - tools/deploy_documentation_dev.sh \ No newline at end of file + - name: Build docs dev + run: EXPERIMENTS_DEV_DOCS=1 PROD_BUILD=1 RELEASE_STRING=`git describe` tox -edocs + - name: Bypass Jekyll Processing # Necessary for setting the correct css path + run: touch docs/_build/html/.nojekyll + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/_build/html/ + target-folder: dev/ diff --git a/.github/workflows/docs.yml b/.github/workflows/docs_release.yml similarity index 61% rename from .github/workflows/docs.yml rename to .github/workflows/docs_release.yml index 0607301851..e201841b40 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs_release.yml @@ -22,10 +22,16 @@ jobs: python -m pip install --upgrade pip pip install -U virtualenv setuptools wheel tox sudo apt-get install graphviz pandoc - - name: Build and publish + - name: Build docs env: - encrypted_rclone_key: ${{ secrets.encrypted_rclone_key }} - encrypted_rclone_iv: ${{ secrets.encrypted_rclone_iv }} QISKIT_DOCS_BUILD_TUTORIALS: 'always' - run: | - tools/deploy_documentation.sh + run: EXPERIMENTS_DEV_DOCS=1 PROD_BUILD=1 tox -edocs + - name: Bypass Jekyll Processing # Necessary for setting the correct css path + run: touch docs/_build/html/.nojekyll + - name: Deploy + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/_build/html/ + clean-exclude: | + stable/* + dev/* diff --git a/.github/workflows/docs_stable.yml b/.github/workflows/docs_stable.yml new file mode 100644 index 0000000000..58a2767d90 --- /dev/null +++ b/.github/workflows/docs_stable.yml @@ -0,0 +1,38 @@ +name: Stable Docs Publish +on: + workflow_dispatch: + push: + tags: + - "*" + +jobs: + deploy: + if: github.repository_owner == 'Qiskit-Extensions' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.8' + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -U virtualenv setuptools wheel tox + sudo apt-get install graphviz pandoc + - name: Build docs stable + env: + QISKIT_DOCS_BUILD_TUTORIALS: 'always' + run: EXPERIMENTS_DEV_DOCS=1 PROD_BUILD=1 tox -e docs + - name: Bypass Jekyll Processing # Necessary for setting the correct css path + run: touch docs/_build/html/.nojekyll + - name: Set current version + run: | + echo "version=$(git describe --abbrev=0 | cut -d'.' -f1,2)" >> "$GITHUB_ENV" + - name: Deploy stable + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: docs/_build/html + target-folder: stable/${{ env.version }} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index b2165afb6b..33130e4a65 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -162,7 +162,7 @@ html_title = f"{project} {release}" -docs_url_prefix = "ecosystem/experiments" +docs_url_prefix = "qiskit-experiments" html_last_updated_fmt = "%Y/%m/%d" diff --git a/tools/deploy_documentation.sh b/tools/deploy_documentation.sh deleted file mode 100755 index db60323c18..0000000000 --- a/tools/deploy_documentation.sh +++ /dev/null @@ -1,39 +0,0 @@ -#!/bin/bash - -# This code is part of Qiskit. -# -# (C) Copyright IBM 2018, 2023. -# -# This code is licensed under the Apache License, Version 2.0. You may -# obtain a copy of this license in the LICENSE.txt 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. - -# Script for pushing the documentation to the qiskit.org/ecosystem -set -e - -curl https://downloads.rclone.org/rclone-current-linux-amd64.deb -o rclone.deb -sudo apt-get install -y ./rclone.deb - -RCLONE_CONFIG_PATH=$(rclone config file | tail -1) - -# Build the documentation. -EXPERIMENTS_DEV_DOCS=1 PROD_BUILD=1 tox -edocs - -echo "show current dir: " -pwd - -CURRENT_TAG=`git describe --abbrev=0` -IFS=. read -ra VERSION <<< "$CURRENT_TAG" -STABLE_VERSION=${VERSION[0]}.${VERSION[1]} -echo "Building for stable version $STABLE_VERSION" - -# Push to qiskit.org/ecosystem -openssl aes-256-cbc -K $encrypted_rclone_key -iv $encrypted_rclone_iv -in tools/rclone.conf.enc -out $RCLONE_CONFIG_PATH -d -echo "Pushing built docs to website" -rclone sync --progress --exclude-from ./tools/other-builds.txt ./docs/_build/html IBMCOS:qiskit-org-web-resources/ecosystem/experiments -echo "Pushing $STABLE_VERSION built docs to website" -rclone sync --progress ./docs/_build/html IBMCOS:qiskit-org-web-resources/ecosystem/experiments/stable/"$STABLE_VERSION" diff --git a/tools/deploy_documentation_dev.sh b/tools/deploy_documentation_dev.sh deleted file mode 100755 index 1f3255fc03..0000000000 --- a/tools/deploy_documentation_dev.sh +++ /dev/null @@ -1,32 +0,0 @@ -#!/bin/bash - -# This code is part of Qiskit. -# -# (C) Copyright IBM 2018, 2019. -# -# This code is licensed under the Apache License, Version 2.0. You may -# obtain a copy of this license in the LICENSE.txt 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. - -# Script for pushing the documentation to the qiskit.org repository. -set -e - -curl https://downloads.rclone.org/rclone-current-linux-amd64.deb -o rclone.deb -sudo apt-get install -y ./rclone.deb - -RCLONE_CONFIG_PATH=$(rclone config file | tail -1) - -# Build the documentation. -EXPERIMENTS_DEV_DOCS=1 PROD_BUILD=1 RELEASE_STRING=`git describe` tox -edocs - -echo "show current dir: " -pwd - -# Push to qiskit.org website -openssl aes-256-cbc -K $encrypted_rclone_key -iv $encrypted_rclone_iv -in tools/rclone.conf.enc -out $RCLONE_CONFIG_PATH -d -echo "Pushing built docs to dev website" -rclone sync --progress ./docs/_build/html IBMCOS:qiskit-org-web-resources/ecosystem/experiments/dev diff --git a/tools/rclone.conf.enc b/tools/rclone.conf.enc deleted file mode 100644 index 985bd728abc0a83d8ea98cd4d9561b7fa124842f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 304 zcmV-00nh$7&RTYTNLa46ND6UrOuMoPNp}L^N21;+KWICI2ddxLf?x*g*GAzexAhvW z5rTO-?xi4$c>vaY~!DfD~lI0H5)o5;H>qj7M~)ZT{14Fvc91%J)Ycl~B`S zR;dTAK}Qz7!C#ExhwZKgVKh_&DPch2pvl7`Df`TB7^fDm2w+?}@Ltb_s9A^-JfyD- zcV@+wP8bfhSO=k!OfNS+tVO*B2xkEIky>2YRz;z0Ar#-=dP|4$ar~If5$=F}D=bc3 C!HCcR