Deploy docs to GitHub Pages (backport #1356) (#1365)

This is an automatic backport of pull request #1356 done by
[Mergify](https://mergify.com).
Cherry-pick of b605472 has failed:
```
On branch mergify/bp/stable/0.5/pr-1356
Your branch is up to date with 'origin/stable/0.5'.

You are currently cherry-picking commit b605472.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
	modified:   .github/workflows/docs_dev.yml
	renamed:    .github/workflows/docs.yml -> .github/workflows/docs_release.yml
	new file:   .github/workflows/docs_stable.yml
	deleted:    tools/rclone.conf.enc

Unmerged paths:
  (use "git add/rm <file>..." as appropriate to mark resolution)
	both modified:   docs/conf.py
	deleted by them: tools/deploy_documentation.sh
	deleted by them: tools/deploy_documentation_dev.sh

```


To fix up this pull request, you can check it out locally. See
documentation:
https://docs.github.com/en/github/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

---


<details>
<summary>Mergify commands and options</summary>

<br />

More conditions and actions can be found in the
[documentation](https://docs.mergify.com/).

You can also trigger Mergify actions by commenting on this pull request:

- `@Mergifyio refresh` will re-evaluate the rules
- `@Mergifyio rebase` will rebase this PR on its base branch
- `@Mergifyio update` will merge the base branch into this PR
- `@Mergifyio backport <destination>` will backport this PR on
`<destination>` branch

Additionally, on Mergify [dashboard](https://dashboard.mergify.com) you
can:

- look at your merge queues
- generate the Mergify configuration with the config editor.

Finally, you can contact us on https://mergify.com
</details>

---------

Co-authored-by: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Co-authored-by: Helena Zhang <Helena.Zhang@ibm.com>

.github/workflows/docs_dev.yml

@@ -19,9 +19,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

@@ -20,10 +20,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

@@ -145,6 +145,11 @@
     "expandable_sidebar": True,
 }
 
+
+html_title = f"{project} {release}"
+
+docs_url_prefix = "qiskit-experiments"
+
 html_last_updated_fmt = "%Y/%m/%d"
 
 html_theme_options = {
@@ -160,7 +165,7 @@
     "matplotlib": ("https://matplotlib.org/stable/", None),
     "qiskit": ("https://qiskit.org/documentation/", None),
     "uncertainties": ("https://pythonhosted.org/uncertainties", None),
-    "qiskit_ibm_provider": ("https://qiskit.org/documentation/partners/qiskit_ibm_provider", None),
+    "qiskit_ibm_provider": ("https://docs.quantum.ibm.com/api/qiskit-ibm-provider", None),
 }
 
 

docs/tutorials/calibrations.rst

@@ -15,7 +15,7 @@ backend, :class:`.SingleTransmonTestBackend`, a backend that simulates the under
 pulses with `Qiskit Dynamics <https://qiskit.org/documentation/dynamics/>`_ on a
 three-level model of a transmon. You can also run these experiments on any real backend
 with Pulse enabled (see
-:external+qiskit:doc:`tutorials/circuits_advanced/08_gathering_system_information`).
+:class:`qiskit.providers.models.BackendConfiguration`).
 
 We will run experiments to 
 find the qubit frequency, calibrate the amplitude of DRAG pulses, and choose the value 

docs/tutorials/getting_started.rst

@@ -6,7 +6,7 @@ Installation
 ============
 
 Qiskit Experiments is built on top of Qiskit, so we recommend that you first install
-Qiskit following its :external+qiskit:doc:`installation guide <getting_started>`. Qiskit
+Qiskit following its `installation guide <https://docs.quantum.ibm.com/start/install>`__. Qiskit
 Experiments supports the same platforms and Python versions (currently **3.7+**) as
 Qiskit itself.
 

docs/tutorials/index.rst

@@ -1,8 +1,8 @@
 Tutorials
 =========
 
-These tutorials assume some familiarity with Qiskit (on the level of the 
-:external+qiskit:doc:`introductory tutorials <tutorials>`) but no knowledge of Qiskit Experiments.
+These tutorials assume some familiarity with Qiskit (on the level of 
+`IBM Quantum Documentation's introductory guides <https://docs.quantum.ibm.com>`__) but no knowledge of Qiskit Experiments.
 They're suitable for beginners who want to get started with the package.
 
 .. _basics:

requirements-dev.txt

@@ -24,6 +24,4 @@ sphinx-copybutton
 # Pin versions below because of build errors
 ipykernel<=6.21.3
 jupyter-client<=8.0.3
-# Pin symengine because there are no wheels for 0.10 for Python 3.7
-symengine<=0.9.2;python_version<'3.8'
 ipython<8.13.0 ; python_version<"3.9"  # for python 3.8 compatibility

requirements.txt

@@ -1,6 +1,6 @@
 numpy>=1.17
 scipy>=1.4
-qiskit-terra>=0.22
+qiskit-terra>0.22,<0.25
 qiskit-ibm-experiment>=0.2.5
 qiskit_dynamics>=0.3.0
 matplotlib>=3.4