Add GitHub Actions documentation-deployment pipeline

.azure/docs-linux.yml

@@ -19,16 +19,14 @@ jobs:
           versionSpec: '${{ parameters.pythonVersion }}'
         displayName: 'Use Python ${{ parameters.pythonVersion }}'
 
-      - bash: |
-          set -e
-          python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -U "tox<4.4.0"
-          sudo apt-get update
-          sudo apt-get install -y graphviz pandoc
+      - bash: tools/install_ubuntu_docs_dependencies.sh
         displayName: 'Install dependencies'
 
       - bash: |
-          tox -edocs
+          set -e
+          tox -e docs
+          # Clean up Sphinx detritus.
+          rm -rf docs/_build/html/{.doctrees,.buildinfo}
         displayName: 'Run Docs build'
 
       - task: ArchiveFiles@2

.azure/tutorials-linux.yml

@@ -16,14 +16,10 @@ jobs:
           versionSpec: '${{ parameters.pythonVersion }}'
         displayName: 'Use Python ${{ parameters.pythonVersion }}'
 
-      - bash: |
-          set -e
-          python -m pip install --upgrade pip setuptools wheel
-          python -m pip install -U "tox<4.4.0"
-          sudo apt-get update
-          sudo apt-get install -y graphviz pandoc
+      - bash: tools/install_ubuntu_docs_dependencies.sh
         displayName: 'Install dependencies'
 
+      # Sync with '.github/workflows/docs_deploy.yml'
       - bash: tools/prepare_tutorials.bash algorithms circuits circuits_advanced operators
         displayName: 'Download current tutorials'
 

.github/workflows/docs_deploy.yml

@@ -0,0 +1,224 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - main
+      - 'stable/*'
+    tags:
+      - '*'
+  workflow_dispatch:
+    inputs:
+      deploy_prefix:
+        description: "Deployment prefix (leave blank for the root): https://qiskit.org/documentation/<prefix>."
+        required: false
+        type: string
+      do_deployment:
+        description: "Push to qiskit.org?"
+        required: false
+        type: boolean
+      do_translatables:
+        description: "Push translatable strings?"
+        required: false
+        type: boolean
+
+jobs:
+  build:
+    if: github.repository_owner == "Qiskit"
+    name: Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          # We need to fetch the whole history so 'reno' can do its job.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v4
+        name: Install Python
+        with:
+          # Sync with 'documentationPythonVersion' in 'azure-pipelines.yml'.
+          python-version: '3.9'
+
+      - name: Install dependencies
+        run: tools/install_ubuntu_docs_dependencies.sh
+
+      # Sync with '.azure/tutorials-linux.yml'.
+      - name: Download current tutorials
+        run: tools/prepare_tutorials.bash algorithms circuits circuits_advanced operators
+        shell: bash
+
+      # This is just to have tox create the environment, so we can use it to execute the tutorials.
+      # We want to re-use it later for the build, hence 'tox run --notest' instead of 'tox devenv'.
+      - name: Prepare Python environment
+        run: tox run -e docs --notest
+
+      # The reason to use the custom script rather than letting 'nbsphinx' do its thing normally
+      # within the Sphinx build is so that the execution process is the same as in the test CI.
+      - name: Execute tutorials in place
+        run: .tox/docs/bin/python tools/execute_tutorials.py docs/tutorials
+        env:
+          QISKIT_CELL_TIMEOUT: "300"
+
+      - name: Build documentation
+        # We can skip re-installing the package, since we just did it a couple of steps ago.
+        run: tox run -e docs --skip-pkg-install
+        env:
+          QISKIT_ENABLE_ANALYTICS: "true"
+          # We've already built them.
+          QISKIT_DOCS_BUILD_TUTORIALS: "never"
+
+      - name: Build translatable strings
+        run: tox -e gettext
+        env:
+          # We've already built them.
+          QISKIT_DOCS_BUILD_TUTORIALS: "never"
+
+      - name: Store built documentation artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: qiskit-docs
+          path: |
+            ./docs/_build/html/*
+            !**/.doctrees
+            !**/.buildinfo
+          if-no-files-found: error
+
+      - name: Store translatable strings artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: qiskit-translatables
+          path: ./docs/locale/en/*
+          if-no-files-found: error
+
+  deploy:
+    if: github.event_name != 'workflow_dispatch' || inputs.do_deployment
+    name: Deploy to qiskit.org
+    needs: [build]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          path: qiskit
+
+      - uses: actions/download-artifact@v3
+        with:
+          name: qiskit-docs
+          path: deploy
+
+      - id: choose
+        name: Choose deployment location
+        run: |
+          set -e
+          case ${{ github.event_name }} in
+            push)
+              case ${{ github.ref_name }} in
+                main)
+                  echo "deploy_prefix=dev" >> "$GITHUB_OUTPUT"
+                  ;;
+                # This currently deploys to the documentation root on a push to _any_ stable branch;
+                # when we're supporting more than one version at once, it will need revisiting.
+                stable/*)
+                  echo "deploy_prefix=" >> "$GITHUB_OUTPUT"
+                  ;;
+                *)
+                  echo "Push to unhandled branch ${{ github.ref_name }}" >&2
+                  exit 1
+                  ;;
+              esac
+              ;;
+            tag)
+              tag=${{ github.ref_name }}
+              echo "Full tag: ${tag}"
+              IFS=. read -ra version <<< "$tag"
+              minor_version="${version[0]}.${version[1]}"
+              echo "Minor version: ${minor_version}"
+              echo "deploy_prefix=stable/${minor_version}" >> "$GITHUB_OUTPUT"
+              ;;
+            workflow_dispatch)
+              echo "deploy_prefix=${{ inputs.deploy_prefix }}" >> "$GITHUB_OUTPUT"
+              ;;
+            *)
+              echo "Unhandled GitHub event ${{ github.event_name }}" >&2
+              exit 1
+              ;;
+          esac
+
+      - name: Install rclone
+        run: |
+          set -e
+          curl https://downloads.rclone.org/rclone-current-linux-amd64.deb -o rclone.deb
+          sudo apt-get install -y ./rclone.deb
+
+      - name: Deploy to qiskit.org
+        run: |
+          set -e
+          RCLONE_CONFIG=$(rclone config file | tail -1)
+          openssl aes-256-cbc -K "$RCLONE_KEY" -iv "$RCLONE_IV" -in qiskit/tools/rclone.conf.enc -out "$RCLONE_CONFIG" -d
+          rclone sync --progress --exclude-from qiskit/tools/docs_exclude.txt deploy "IBMCOS:qiskit-org-web-resources/documentation/${{ steps.choose.outputs.deploy_prefix }}"
+        env:
+          RCLONE_KEY: ${{ secrets.encrypted_rclone_key }}
+          RCLONE_IV: ${{ secrets.encrypted_rclone_iv }}
+
+  deploy_translatables:
+    if: (github.event_name == 'workflow_dispatch' && inputs.do_translatables) || (github.event_name == 'push' && startsWith(github.ref_name.startsWith, 'stable/'))
+    name: Push translatable strings
+    needs: [build]
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          path: 'qiskit'
+
+      - uses: actions/download-artifact@v3
+        with:
+          name: qiskit-translatables
+          path: 'deploy'
+
+      - name: Decrypt SSH secret key
+        id: ssh_key
+        run: |
+          set -e
+          ssh_key=$(openssl enc -aes-256-cbc -d -in qiskit/tools/github_poBranch_update_key.enc -K $SSH_UPDATE_KEY -iv $SSH_UPDATE_IV)
+          echo "::add-mask::${ssh_key}"
+          echo "ssh_key=${ssh_key}" >> "$GITHUB_OUTPUT"
+        env:
+          SSH_UPDATE_KEY: ${{ secrets.encrypted_ssh_translatables_key }}
+          SSH_UPDATE_IV: ${{ secrets.encrypted_ssh_translatables_iv }}
+
+      - uses: actions/checkout@v3
+        with:
+          repository: 'qiskit-community/qiskit-translations'
+          path: 'qiskit-translations'
+          ssh-key: '${{ steps.ssh_key.outputs.ssh_key }}'
+
+      - name: Remove ignored documents
+        run: rm -r LC_MESSAGES/{apidocs,stubs}
+        working-directory: 'deploy'
+
+      - name: Push changes to translations repository
+        run: |
+          set -e
+          shopt -s failglob
+          # Bring the new `.po` target files into the repository.
+          git rm -r --ignore-unmatch docs/locale/en
+          mv "${{ github.workspace }}/deploy" docs/locale/en
+          # Update the ways to recreate the build.
+          cp "${{ github.workspace }}/qiskit/"{setup.py,requirements-*.txt,constraints.txt} .
+          git add .
+
+          cat > COMMIT_MSG << EOF
+          Automated documentation update to add .po files from ${{ github.repository }}
+
+          skip ci
+
+          Commit: ${{ github.sha }}
+          GitHub Actions run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          EOF
+
+          git config user.name "Qiskit Autodeploy"
+          git config user.email "qiskit@qiskit.org"
+          git commit -F COMMIT_MSG
+          git push origin
+        working-directory: 'qiskit-translations'

.gitignore

@@ -76,8 +76,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
 
 # PyBuilder
 target/
@@ -118,10 +116,6 @@ tutorial/rst/_build/*
 
 test/python/test_qasm_python_simulator.pdf
 
-doc/_build/*
-
-doc/**/_autodoc
-
 qiskit/bin/*
 
 test/python/test_save.json
@@ -142,8 +136,11 @@ src/qasm-simulator-cpp/test/qubit_vector_tests
 qiskit/transpiler/passes/**/cython/**/*.cpp
 qiskit/quantum_info/states/cython/*.cpp
 
-docs/stubs/*
-executed_tutorials/
+# Sphinx documentation
+/docs/_build
+/docs/stubs
+/docs/locale
+/executed_tutorials
 
 # Notebook testing images
 test/visual/mpl/circuit/circuit_results/*.png

azure-pipelines.yml

@@ -60,6 +60,7 @@ parameters:
     type: string
     default: "3.8"
 
+  # Sync with 'python-version' in '.github/workflows/docs_deploy.yml'.
   - name: "documentationPythonVersion"
     displayName: "Version of Python to use to build Sphinx documentation"
     type: string

docs/conf.py

@@ -27,6 +27,13 @@
 # The full version, including alpha/beta/rc tags
 release = "0.45.0"
 
+# The language for content autogenerated by Sphinx or the default for gettext content translation.
+language = "en"
+
+# For 'qiskit_sphinx_theme' tells it we're based at 'https://qiskit.org/<docs_url_prefix>'.
+# Should not include the subdirectory for the stable version.
+docs_url_prefix = "documentation"
+
 extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
@@ -50,8 +57,20 @@
 # Available keys are 'figure', 'table', 'code-block' and 'section'.  '%s' is the number.
 numfig_format = {"table": "Table %s"}
 
-# The language for content autogenerated by Sphinx or the default for gettext content translation.
-language = "en"
+# Translations configuration.
+translations_list = [
+    ("en", "English"),
+    ("bn_BN", "Bengali"),
+    ("fr_FR", "French"),
+    ("de_DE", "German"),
+    ("ja_JP", "Japanese"),
+    ("ko_KR", "Korean"),
+    ("pt_UN", "Portuguese"),
+    ("es_UN", "Spanish"),
+    ("ta_IN", "Tamil"),
+]
+locale_dirs = ["locale/"]
+gettext_compact = False
 
 # Relative to source directory, affects general discovery, and html_static_path and html_extra_path.
 exclude_patterns = ["_build", "**.ipynb_checkpoints"]
@@ -90,6 +109,9 @@
     "prev_next_buttons_location": "bottom",
     "style_external_links": True,
 }
+html_context = {
+    "analytics_enabled": bool(os.getenv("QISKIT_ENABLE_ANALYTICS", ""))
+}  # enable segment analytics for qiskit.org/documentation
 
 # ----------------------------------------------------------------------------------
 # Autodoc

tools/docs_exclude.txt

@@ -0,0 +1,3 @@
+/stable/**
+/locale/**
+/dev/**

tools/install_ubuntu_docs_dependencies.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+#
+# Prepare an Ubuntu CI machine for running 'tox -e docs'.  Assumes that Python is available.
+
+set -e
+
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install --upgrade "tox<4.4.0"
+
+sudo apt-get update
+sudo apt-get install -y graphviz pandoc