Skip to content

Commit 965fd23

Browse files
authored
Migrate documentation and benchmarks from metapackage (Qiskit#10611)
### Summary 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. ### Details and comments 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.
2 parents 6a7d109 + 66a5d9f commit 965fd23

File tree

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

105 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.45.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),
@@ -82,14 +108,13 @@
82108
# HTML theme
83109
# ----------------------------------------------------------------------------------
84110

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

94119
# ----------------------------------------------------------------------------------
95120
# Autodoc
@@ -106,6 +131,8 @@
106131
# return type is always added to the description (if in the signature).
107132
autodoc_typehints_description_target = "documented_params"
108133

134+
autoclass_content = "both"
135+
109136
autosummary_generate = True
110137
autosummary_generate_overwrite = False
111138

@@ -126,8 +153,6 @@
126153
"qiskit.pulse.library.Sech": "qiskit.pulse.library.Sech_fun.rst",
127154
}
128155

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

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

0 commit comments

Comments
 (0)