Skip to content

Commit cd2d485

Browse files
jakelishmanSamD-1998
authored andcommitted
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.
1 parent 17f2a4e commit cd2d485

11 files changed

+336
-34
lines changed

.azure/docs-linux.yml

+5-7
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,14 @@ jobs:
1919
versionSpec: '${{ parameters.pythonVersion }}'
2020
displayName: 'Use Python ${{ parameters.pythonVersion }}'
2121

22-
- bash: |
23-
set -e
24-
python -m pip install --upgrade pip setuptools wheel
25-
python -m pip install -U "tox<4.4.0"
26-
sudo apt-get update
27-
sudo apt-get install -y graphviz pandoc
22+
- bash: tools/install_ubuntu_docs_dependencies.sh
2823
displayName: 'Install dependencies'
2924

3025
- bash: |
31-
tox -edocs
26+
set -e
27+
tox -e docs
28+
# Clean up Sphinx detritus.
29+
rm -rf docs/_build/html/{.doctrees,.buildinfo}
3230
displayName: 'Run Docs build'
3331
3432
- task: ArchiveFiles@2

.azure/tutorials-linux.yml

+2-6
Original file line numberDiff line numberDiff line change
@@ -16,14 +16,10 @@ jobs:
1616
versionSpec: '${{ parameters.pythonVersion }}'
1717
displayName: 'Use Python ${{ parameters.pythonVersion }}'
1818

19-
- bash: |
20-
set -e
21-
python -m pip install --upgrade pip setuptools wheel
22-
python -m pip install -U "tox<4.4.0"
23-
sudo apt-get update
24-
sudo apt-get install -y graphviz pandoc
19+
- bash: tools/install_ubuntu_docs_dependencies.sh
2520
displayName: 'Install dependencies'
2621

22+
# Sync with '.github/workflows/docs_deploy.yml'
2723
- bash: tools/prepare_tutorials.bash algorithms circuits circuits_advanced operators
2824
displayName: 'Download current tutorials'
2925

.gitignore

+5-8
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,6 @@ instance/
7676
# Scrapy stuff:
7777
.scrapy
7878

79-
# Sphinx documentation
80-
docs/_build/
8179

8280
# PyBuilder
8381
target/
@@ -119,10 +117,6 @@ tutorial/rst/_build/*
119117

120118
test/python/test_qasm_python_simulator.pdf
121119

122-
doc/_build/*
123-
124-
doc/**/_autodoc
125-
126120
qiskit/bin/*
127121

128122
test/python/test_save.json
@@ -143,8 +137,11 @@ src/qasm-simulator-cpp/test/qubit_vector_tests
143137
qiskit/transpiler/passes/**/cython/**/*.cpp
144138
qiskit/quantum_info/states/cython/*.cpp
145139

146-
docs/stubs/*
147-
executed_tutorials/
140+
# Sphinx documentation
141+
/docs/_build
142+
/docs/stubs
143+
/docs/locale
144+
/executed_tutorials
148145

149146
# Notebook testing images
150147
test/visual/mpl/circuit/circuit_results/*.png

azure-pipelines.yml

+1
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ parameters:
6060
type: string
6161
default: "3.8"
6262

63+
# Sync with 'python-version' in '.github/workflows/docs_deploy.yml'.
6364
- name: "documentationPythonVersion"
6465
displayName: "Version of Python to use to build Sphinx documentation"
6566
type: string

docs/conf.py

+30-6
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,12 @@
3737
# The full version, including alpha/beta/rc tags
3838
release = "0.44.0"
3939

40-
docs_url_prefix = "documentation" # i.e., www.qiskit.org/documentation/
40+
# The language for content autogenerated by Sphinx or the default for gettext content translation.
41+
language = "en"
42+
43+
# For 'qiskit_sphinx_theme' tells it we're based at 'https://qiskit.org/<docs_url_prefix>'.
44+
# Should not include the subdirectory for the stable version.
45+
docs_url_prefix = "documentation"
4146

4247
rst_prolog = """
4348
.. |version| replace:: {0}
@@ -60,10 +65,29 @@
6065
"sphinx.ext.intersphinx",
6166
]
6267

63-
nbsphinx_timeout = 300
64-
nbsphinx_execute = os.getenv("QISKIT_DOCS_BUILD_TUTORIALS", "never")
65-
nbsphinx_widgets_path = ""
66-
html_sourcelink_suffix = ""
68+
templates_path = ["_templates"]
69+
70+
# Number figures, tables and code-blocks if they have a caption.
71+
numfig = True
72+
# Available keys are 'figure', 'table', 'code-block' and 'section'. '%s' is the number.
73+
numfig_format = {"table": "Table %s"}
74+
75+
# Translations configuration.
76+
translations_list = [
77+
("en", "English"),
78+
("bn_BN", "Bengali"),
79+
("fr_FR", "French"),
80+
("de_DE", "German"),
81+
("ja_JP", "Japanese"),
82+
("ko_KR", "Korean"),
83+
("pt_UN", "Portuguese"),
84+
("es_UN", "Spanish"),
85+
("ta_IN", "Tamil"),
86+
]
87+
locale_dirs = ["locale/"]
88+
gettext_compact = False
89+
90+
# Relative to source directory, affects general discovery, and html_static_path and html_extra_path.
6791
exclude_patterns = ["_build", "**.ipynb_checkpoints"]
6892

6993
nbsphinx_thumbnails = {"**": "_static/images/logo.png"}
@@ -152,7 +176,7 @@
152176
html_favicon = "images/favicon.ico"
153177
html_last_updated_fmt = "%Y/%m/%d"
154178
html_context = {
155-
"analytics_enabled": os.getenv("QISKIT_ENABLE_ANALYTICS", False)
179+
"analytics_enabled": bool(os.getenv("QISKIT_ENABLE_ANALYTICS", ""))
156180
} # enable segment analytics for qiskit.org/documentation
157181

158182
# -- Options for Autosummary and Autodoc ------------------------------------

tools/docs_exclude.txt

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/stable/**
2+
/locale/**
3+
/dev/**

tools/github_poBranch_update_key.enc

3.33 KB
Binary file not shown.
+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/bin/sh
2+
#
3+
# Prepare an Ubuntu CI machine for running 'tox -e docs'. Assumes that Python is available.
4+
5+
set -e
6+
7+
python -m pip install --upgrade pip setuptools wheel
8+
python -m pip install --upgrade "tox<4.4.0"
9+
10+
sudo apt-get update
11+
sudo apt-get install -y graphviz pandoc

tools/rclone.conf.enc

304 Bytes
Binary file not shown.

tox.ini

+13-7
Original file line numberDiff line numberDiff line change
@@ -73,11 +73,12 @@ setenv =
7373
{[testenv]setenv}
7474
QISKIT_SUPPRESS_PACKAGING_WARNINGS=Y
7575
RUST_DEBUG=1 # Faster to compile.
76-
passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS
76+
passenv = {[testenv]passenv}, QISKIT_DOCS_BUILD_TUTORIALS, QISKIT_CELL_TIMEOUT
7777
deps =
7878
setuptools_rust # This is work around for the bug of tox 3 (see #8606 for more details.)
7979
-r{toxinidir}/requirements-dev.txt
8080
-r{toxinidir}/requirements-optional.txt
81+
-r{toxinidir}/requirements-tutorials.txt
8182
# Some optionals depend on Terra. We want to make sure pip satisfies that requirement from a local
8283
# installation, not from PyPI. But Tox normally doesn't install the local installation until
8384
# after `deps` is installed. So, instead, we tell pip to do the local installation at the same
@@ -92,13 +93,18 @@ deps =
9293
allowlist_externals =
9394
rm
9495
commands =
95-
rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build
96+
rm -rf {toxinidir}/docs/stubs/ {toxinidir}/docs/_build {toxinidir}/docs/locale
9697

9798
[testenv:tutorials]
98-
basepython = python3
99-
deps =
100-
{[testenv:docs]deps}
101-
-r{toxinidir}/requirements-tutorials.txt
102-
passenv = {[testenv]passenv}, QISKIT_CELL_TIMEOUT
99+
base = docs
103100
commands =
104101
python tools/execute_tutorials.py {toxinidir}/docs/tutorials --out={toxinidir}/executed_tutorials {posargs}
102+
103+
[testenv:gettext]
104+
base = docs
105+
deps =
106+
{[testenv:docs]deps}
107+
sphinx-intl
108+
commands =
109+
sphinx-build -b gettext docs docs/_build/gettext {posargs}
110+
sphinx-intl -c docs/conf.py update -p docs/_build/gettext -l en -d docs/locale

0 commit comments

Comments
 (0)