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: Qiskit/ecosystem#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 <[email protected]>

.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
+    - 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/

.github/workflows/docs.yml → .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/*

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

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"