Skip to content

Commit fc970a6

Browse files
committed
Migrate documentation and benchmarks from metapackage (Qiskit#10611)
This cross-repository merge unifies the documentation, benchmarks and code of conduct from the metapackage into Qiskit/Terra's build. There are very non-trivial merge conflicts that have been resolved by this commit. The summary is: - `CODE_OF_CONDUCT.md`: taken directly from the metapackage's version. - `docs/conf.py`: strongly unified, albeit without the translations components that are added in a separate commit. - `docs/index.rst`: taken almost verbatim from the metapackage. All the API documentation RST files on Terra are moved to `docs/apidoc` (without the trailing 's') to match the metapackage expectation, so the URLs of built documentation will not change. - `docs/release_notes.rst`: The metapackage's version is renamed to `docs/legacy_release_notes.rst`, given a small introductory header, and made an orphan linked only from a _new_ `docs/release_notes.rst` that uses `reno`. - `docs/tutorials.rst`: Mostly these were the same already. Updated to include Qiskit/Terra's correction that it's not an orphan, and contain the metapackage's extra intro tutorial. - `docs/apidoc/terra.rst`: renamed to `docs/apidoc/index.rst` and retitled to be correctly just "API Documentation". - `requirements-dev.txt`: the version of the Sphinx theme is bumped to 1.14 to match the metapackage expectation. Following merge commit ec5c9ca, there is a commit 66a5d9f that fixes the ASV build for use in Terra, which is the rollup of the post-merge commits of Qiskit#10546, which this PR supersedes. This should probably be merged ASAP before `main` moves on. Resolutions on the metapackage: - Fix Qiskit/qiskit-metapackage#1723 - Fix Qiskit/qiskit-metapackage#1722 - Fix Qiskit/qiskit-metapackage#1746 After this has merged, Qiskit#10610 should merge which will close the remaining migration-related issues from the metapackage. The metapackage was prepared for the migration using [`git-filter-repo`](https://github.com/newren/git-filter-repo), with the scripts and configuration files contained within [metapackage_migration.zip](https://github.com/Qiskit/qiskit-terra/files/12324298/metapackage_migration.zip). If you extract that zip, you need to activate a Python 3.11 `venv` then run `metapackage_rewrite.bash` which will prepare the repo in the exact state I merged to create this PR. *edit*: In retrospect writing this, you might need to modify my script so that it pulls only starting from commit Qiskit/qiskit-metapackage@f131daf, which was the tip of `master` at the time I ran this. I tested the docs build locally and it looks as correct as I can tell. There's still big cards pointing to experiments, dynamics etc on the landing page, but I figured that enough's enough, and we can just fix those last two things in Terra. This PR does not include Qiskit/qiskit-metapackage#1791, which should be now cherry-picked onto Terra. (cherry picked from commit 965fd23)
1 parent ef8ae34 commit fc970a6

File tree

104 files changed

+48736
-38
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

104 files changed

+48736
-38
lines changed

.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ celerybeat-schedule
9898
.env
9999

100100
# virtualenv
101+
.asv/
101102
.venv
102103
venv/
103104
ENV/

CODE_OF_CONDUCT.md

+111-6

asv.conf.json

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"version": 1,
3+
"project": "qiskit",
4+
"project_url": "https://qiskit.org",
5+
"repo": ".",
6+
"install_command": [
7+
"in-dir={env_dir} python -mpip install {wheel_file}[all] python-constraint qiskit-experiments==0.3.0"
8+
],
9+
"uninstall_command": [
10+
"return-code=any python -mpip uninstall -y {project}"
11+
],
12+
"build_command": [
13+
"pip install -U setuptools-rust",
14+
"python setup.py build_rust --release",
15+
"PIP_NO_BUILD_ISOLATION=false python -mpip wheel --no-deps --no-index -w {build_cache_dir} {build_dir}"
16+
],
17+
"branches": ["main"],
18+
"dvcs": "git",
19+
"environment_type": "virtualenv",
20+
"show_commit_url": "http://github.com/Qiskit/qiskit-terra/commit/",
21+
"pythons": ["3.8", "3.9", "3.10", "3.11"],
22+
"benchmark_dir": "test/benchmarks",
23+
"env_dir": ".asv/env",
24+
"results_dir": ".asv/results"
25+
}

docs/_static/images/ibm_qlab.png

80.7 KB

docs/_static/images/strangeworks.png

93.3 KB

docs/apidocs/terra.rst docs/apidoc/index.rst

+3-3

docs/conf.py

+68-10
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,14 @@
1010
# copyright notice, and modified files need to carry a notice indicating
1111
# that they have been altered from the originals.
1212

13-
# pylint: disable=invalid-name
13+
# pylint: disable=invalid-name,missing-function-docstring
1414

1515
"""Sphinx documentation builder."""
1616

1717
import datetime
1818
import doctest
1919
import os
20+
import subprocess
2021

2122
project = "Qiskit"
2223
project_copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"
@@ -27,6 +28,12 @@
2728
# The full version, including alpha/beta/rc tags
2829
release = "0.25.0"
2930

31+
# For 'qiskit_sphinx_theme' tells it we're based at 'https://qiskit.org/<docs_url_prefix>'.
32+
# Should not include the subdirectory for the stable version.
33+
docs_url_prefix = "documentation"
34+
35+
rst_prolog = f".. |version| replace:: {version}"
36+
3037
extensions = [
3138
"sphinx.ext.napoleon",
3239
"sphinx.ext.autodoc",
@@ -58,6 +65,12 @@
5865

5966
pygments_style = "colorful"
6067

68+
panels_css_variables = {
69+
"tabs-color-label-active": "rgb(138, 63, 252)",
70+
"tabs-color-label-inactive": "rgb(221, 225, 230)",
71+
}
72+
73+
6174
# This adds the module name to e.g. function API docs. We use the default of True because our
6275
# module pages sometimes have functions from submodules on the page, and we want to make clear
6376
# that you must include the submodule to import it. We should strongly consider reorganizing our
@@ -70,6 +83,19 @@
7083
# (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F).
7184
modindex_common_prefix = ["qiskit."]
7285

86+
# ----------------------------------------------------------------------------------
87+
# Extlinks
88+
# ----------------------------------------------------------------------------------
89+
# Refer to https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
90+
extlinks = {
91+
"pull_terra": ("https://github.com/Qiskit/qiskit-terra/pull/%s", "qiskit-terra #%s"),
92+
"pull_aer": ("https://github.com/Qiskit/qiskit-aer/pull/%s", "qiskit-aer #%s"),
93+
"pull_ibmq-provider": (
94+
"https://github.com/Qiskit/qiskit-ibmq-provider/pull/%s",
95+
"qiskit-ibmq-provider #%s",
96+
),
97+
}
98+
7399
intersphinx_mapping = {
74100
"rustworkx": ("https://qiskit.org/ecosystem/rustworkx/", None),
75101
"qiskit-ibm-runtime": ("https://qiskit.org/ecosystem/ibm-runtime/", None),
@@ -83,14 +109,13 @@
83109
# HTML theme
84110
# ----------------------------------------------------------------------------------
85111

86-
html_theme = "qiskit_sphinx_theme"
112+
html_theme = "qiskit"
113+
html_favicon = "images/favicon.ico"
87114
html_last_updated_fmt = "%Y/%m/%d"
88-
html_theme_options = {
89-
"logo_only": True,
90-
"display_version": True,
91-
"prev_next_buttons_location": "bottom",
92-
"style_external_links": True,
93-
}
115+
html_context = {
116+
"analytics_enabled": os.getenv("QISKIT_ENABLE_ANALYTICS", False)
117+
} # enable segment analytics for qiskit.org/documentation
118+
html_static_path = ["_static"]
94119

95120
# ----------------------------------------------------------------------------------
96121
# Autodoc
@@ -107,6 +132,8 @@
107132
# return type is always added to the description (if in the signature).
108133
autodoc_typehints_description_target = "documented_params"
109134

135+
autoclass_content = "both"
136+
110137
autosummary_generate = True
111138
autosummary_generate_overwrite = False
112139

@@ -127,8 +154,6 @@
127154
"qiskit.pulse.library.Sech": "qiskit.pulse.library.Sech_fun.rst",
128155
}
129156

130-
autoclass_content = "both"
131-
132157
# We only use Google-style docstrings, and allowing Napoleon to parse Numpy-style docstrings both
133158
# slows down the build (a little) and can sometimes result in _regular_ section headings in
134159
# module-level documentation being converted into surprising things.
@@ -153,6 +178,14 @@
153178
# output
154179
doctest_test_doctest_blocks = ""
155180

181+
182+
# ----------------------------------------------------------------------------------
183+
# Plot directive
184+
# ----------------------------------------------------------------------------------
185+
186+
plot_html_show_formats = False
187+
188+
156189
# ----------------------------------------------------------------------------------
157190
# Nbsphinx
158191
# ----------------------------------------------------------------------------------
@@ -176,3 +209,28 @@
176209
__ https://github.com/Qiskit/qiskit-terra/blob/main/{{ docname }}
177210
178211
"""
212+
213+
214+
def add_versions_to_config(_app, config):
215+
"""Add a list of old documentation versions that should have links generated to them into the
216+
context, so the theme can use them to generate a sidebar."""
217+
# First 0.x version where Qiskit/Terra and the metapackage aligned on number.
218+
first_unified_zero_minor = 45
219+
220+
# Start with the hardcoded versions of the documentation that were managed while the metapackage
221+
# still existed, so are based on tags that don't exist in the Qiskit package repo.
222+
versions = ["0.19"] + [f"0.{x}" for x in range(24, first_unified_zero_minor)]
223+
224+
proc = subprocess.run(["git", "describe", "--abbrev=0"], capture_output=True, check=True)
225+
current_version = proc.stdout.decode("utf8")
226+
current_version_info = current_version.split(".")
227+
if current_version_info[0] != "0":
228+
raise Exception("TODO: handle major versions")
229+
versions.extend(
230+
f"0.{x}" % x for x in range(first_unified_zero_minor, int(current_version_info[1]) + 1)
231+
)
232+
config.html_context["version_list"] = versions
233+
234+
235+
def setup(app):
236+
app.connect("config-inited", add_versions_to_config)

0 commit comments

Comments
 (0)