Add GitHub Actions documentation-deployment pipeline (Qiskit#10610)

* Add GitHub Actions documentation-deployment pipeline

This brings a documentation-deployment pipeline into the Qiskit/Terra
repository, allowing it to fully deploy its documentation to
`qiskit.org`, a task previously only the metapackage could perform.
This does not fully unify the documentation with files from the
metapackage, it just adds a pipeline to do the final deployment.

This includes a revitalised translatable-strings pipeline, which was
previously broken on the metapackage for the last month or two. It also
previously included a fair amount of legacy weight that was no longer
relevant.

* Add missing secret insertions

* Improve logic for deployments

This changes the logic for the deployments so that pushes to 'stable/*'
no longer trigger any deployment to qiskit.org.  Instead, tag events
trigger a deployment to the relevant stable branch, and a tag event of
the _latest_ tag triggers a deployment to the documentation root.

The translatables logic is modified to push only the latest full-release
tag.

Author: jakelishman

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

.gitignore

@@ -76,8 +76,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
 
 # PyBuilder
 target/
@@ -119,10 +117,6 @@ tutorial/rst/_build/*
 
 test/python/test_qasm_python_simulator.pdf
 
-doc/_build/*
-
-doc/**/_autodoc
-
 qiskit/bin/*
 
 test/python/test_save.json
@@ -143,8 +137,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

@@ -37,7 +37,12 @@
 # The full version, including alpha/beta/rc tags
 release = "0.44.0"
 
-docs_url_prefix = "documentation"  # i.e., www.qiskit.org/documentation/
+# 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"
 
 rst_prolog = """
 .. |version| replace:: {0}
@@ -60,10 +65,29 @@
     "sphinx.ext.intersphinx",
 ]
 
-nbsphinx_timeout = 300
-nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never")
-nbsphinx_widgets_path = ""
-html_sourcelink_suffix = ""
+templates_path = ["_templates"]
+
+# Number figures, tables and code-blocks if they have a caption.
+numfig = True
+# Available keys are 'figure', 'table', 'code-block' and 'section'.  '%s' is the number.
+numfig_format = {"table": "Table %s"}
+
+# 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"]
 
 nbsphinx_thumbnails = {"**": "_static/images/logo.png"}
@@ -152,7 +176,7 @@
 html_favicon = "images/favicon.ico"
 html_last_updated_fmt = "%Y/%m/%d"
 html_context = {
-    "analytics_enabled": os.getenv("QISKIT_ENABLE_ANALYTICS", False)
+    "analytics_enabled": bool(os.getenv("QISKIT_ENABLE_ANALYTICS", ""))
 }  # enable segment analytics for qiskit.org/documentation
 
 # -- Options for Autosummary and Autodoc ------------------------------------

tools/docs_exclude.txt

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

tools/github_poBranch_update_key.enc

@@ -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

tools/install_ubuntu_docs_dependencies.sh

@@ -73,11 +73,12 @@ setenv =
   {[testenv]setenv}
   QISKIT_SUPPRESS_PACKAGING_WARNINGS=Y
   RUST_DEBUG=1  # Faster to compile.
-passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS
+passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS, QISKIT_CELL_TIMEOUT
 deps =
   setuptools_rust  # This is work around for the bug of tox 3 (see #8606 for more details.)
   -r{toxinidir}/requirements-dev.txt
   -r{toxinidir}/requirements-optional.txt
+  -r{toxinidir}/requirements-tutorials.txt
   # Some optionals depend on Terra. We want to make sure pip satisfies that requirement from a local
   # installation, not from PyPI. But Tox normally doesn't install the local installation until
   # after `deps` is installed. So, instead, we tell pip to do the local installation at the same
@@ -92,13 +93,18 @@ deps =
 allowlist_externals =
   rm
 commands =
-  rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build
+  rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build {toxinidir}/docs/locale
 
 [testenv:tutorials]
-basepython = python3
-deps =
-  {[testenv:docs]deps}
-  -r{toxinidir}/requirements-tutorials.txt
-passenv = {[testenv]passenv}, QISKIT_CELL_TIMEOUT
+base = docs
 commands =
   python tools/execute_tutorials.py {toxinidir}/docs/tutorials --out={toxinidir}/executed_tutorials {posargs}
+
+[testenv:gettext]
+base = docs
+deps =
+    {[testenv:docs]deps} 
+    sphinx-intl
+commands =
+    sphinx-build -b gettext docs docs/_build/gettext {posargs}
+    sphinx-intl -c docs/conf.py update -p docs/_build/gettext -l en -d docs/locale