Set up link redirect strategy #216
Description
Per https://medium.com/qiskit/important-changes-to-qiskit-documentation-and-learning-resources-7f4e346b19ab, qiskit.org/documentation is moving to https://docs.quantum-computing.ibm.com. This issue is to track setting up redirects.
We will not delete the files in Cloud Object Storage for some time. We'll only set up redirects. That allows us to have a fallback like turning off redirects if necessary.
Strategy: all server-side
We have two options:
- CloudFlare rules to implement server-side redirects
- sphinx-reredirects to implement client-side redirects (via meta refresh](https://www.w3.org/TR/WCAG20-TECHS/H76.html)
The web standards recommend server side redirects:
Redirects are preferably implemented on the server side (see SVR1: Implementing automatic redirects on the server side instead of on the client side (SERVER) ), but authors do not always have control over server-side technologies.
https://audisto.com/guides/redirects/#meta-content-refresh warns that client side redirects via meta refresh can also hurt our SEO.
The final issue with client-side redirects is it blocks us from implementing certain wildcard patterns in server-side rules. Server-side rules take precedence over client-side, so if we had an overly general wildcard in CloudFlare like qiskit.org/documentation/*, it would override all of our more granular redirects for specific pages. Whereas if we keep all the config in CloudFlare, we can order our rules to establish precedence, such that wildcards like * are only fall backs.
Therefore, we'll only use CloudFlare server-side redirects.
Qiskit
API docs
There's a 1:1 mapping. We have two types of API pages:
- module pages, e.g. https://qiskit.org/documentation/apidoc/circuit.html (and
index.html) - stub pages, e.g. https://qiskit.org/documentation/stubs/qiskit.circuit.QuantumCircuit.html
We need to also deal with existing redirects for functions -> module pages. These should move to server-side configuration.
How tos ✅
| original | redirect | status |
|---|---|---|
| index.html | /run/primitives-get-started | ✅ |
| Compute circuit output probabilities with Sampler | /run/primitives-get-started | ✅ |
| Compute an expectation value with Estimator | /run/primitives-get-started | ✅ |
Explanation ✅
| original | redirect | status |
|---|---|---|
| index.html | /build/bit-ordering | ✅ |
| Order of Qubits in Qiskit | /build/bit-ordering | ✅ |
Tutorials ✅
index.html: /build ✅
Quantum circuits:
| original | redirect | status |
|---|---|---|
| Circuit basics | /build/circuit-construction | ✅ |
| Getting started with Qiskit | /start/hello-world | ✅ |
| Qiskit visualizations | /build/circuit-visualization | ✅ |
| Summary of Quantum Operations | /build/circuit-construction | ✅ |
Advanced circuits:
| original | redirect | status |
|---|---|---|
| Advanced circuits | /build/circuit-construction | ✅ |
| Operators | /build/operators-overview | ✅ |
| Visualizing a Quantum circuit | /build/circuit-visualization | ✅ |
| Transpiler passes and pass manager | /transpile | ✅ |
| Pulse gates | /build/pulse | ✅ |
| Building pulse schedules | /build/pulse | ✅ |
| Using the scheduler | /build/pulse | ✅ |
| Obtaining information about your backend | /run/get-backend-information |
Operators:
| original | redirect | status |
|---|---|---|
| Operator flow | https://github.com/Qiskit/qiskit/blob/stable/0.46/docs/tutorials/operators/01_operator_flow.ipynb | ✅ |
| Qiskit Gradient Framework | https://github.com/Qiskit/qiskit/blob/stable/0.46/docs/tutorials/operators/02_gradients_framework.ipynb | ✅ |
Migration guides ✅
| original | redirect | status |
|---|---|---|
| index.html | /api/migration-guides | ✅ |
| Algorithms | /api/migration-guides/qiskit-algorithms-module | ✅ |
| Opflow | /api/migration-guides/qiskit-opflow-module | ✅ |
| Quantum Instance | /api/migration-guides/qiskit-quantum-instance | ✅ |
Contributor docs ✅
| original | redirect | status |
|---|---|---|
| Contributing to Qiskit | https://github.com/Qiskit/qiskit/blob/main/CONTRIBUTING.md | ✅ |
| Deprecation Policy | https://github.com/Qiskit/qiskit/blob/main/DEPRECATION.md | ✅ |
| Maintainers Guide | https://github.com/Qiskit/qiskit/blob/main/MAINTAINING.md | ✅ |
Other ✅
| original | redirect | status |
|---|---|---|
| index.html | https://docs.quantum-computing.ibm.com | ✅ |
| Quantum computing in a nutshell | /start/hello-world | ✅ |
| Getting started | /start/install | ✅ |
| Intro to Qiskit | /start/hello-world | ✅ |
| FAQ | /support | ✅ |
| Local configuration | /start/configure-qiskit-local | ✅ |
| Release notes | /api/qiskit/release-notes | ✅ |
| Legacy release notes (orphan) | /api/qiskit/release-notes | ✅ |
Stable docs versions ✅
API docs will go to appropriate place in API docs. Other pages will use the rest of the mapping.
The URL scheme looks like this: qiskit.org/documentation/stable/<version>/rest-of-url.
Versions are 0.19, then 0.25-0.45. Even though 0.45 is the current release, it has its stable URL too.
Translations ✅
Should redirect to English for now. Make sure we account for them with every URL.
The URL scheme looks like this: qiskit.org/documentation/locale/<code>/rest-of-url. Codes: bn_BN, fr_FR, de_DE, ja_JP, ko_KR, pt_UN, es_UN, ta_IN
No fallback redirect ✅
It's too risky that we break pages like objects.inv, used for Sphinx. Instead, we'll rely on the redesigned 404 page to redirect people where to go if the page no longer exists.
Provider 🚢
Tutorials 🚢
| original | redirect | status |
|---|---|---|
| The IBM Quantum Account | https://github.com/Qiskit/qiskit-ibm-provider/blob/stable/0.7/docs/tutorials/1_the_ibm_quantum_account.ipynb | 🚢 |
| Qiskit Jupyter Tools | https://github.com/Qiskit/qiskit-ibm-provider/blob/stable/0.7/docs/tutorials/2_jupyter_tools.ipynb | 🚢 |
| tutorials.html (index) | https://github.com/Qiskit/qiskit-ibm-provider/tree/stable/0.7/docs/tutorials | 🚢 |
Other 🚢
| original | redirect | status |
|---|---|---|
| index.html | /api/qiskit-ibm-provider | 🚢 |
| Release notes | /api/qiskit-ibm-provider/release-notes | 🚢 |
| Migration Guide from qiskit-ibmq-provider | https://github.com/Qiskit/qiskit-ibm-provider/blob/stable/0.7/docs/tutorials/Migration_Guide_from_qiskit-ibmq-provider.ipynb | 🚢 |
API docs 🚢
This is like Qiskit that there's a 1:1 mapping. Note that the index page is called ibm_provider.html in qiskit.org, but should go to /index.
No fallback redirect
Same reason as Qiskit
Runtime ✅
Get started ✅
| original | redirect | status |
|---|---|---|
| Overview (index.html) | /run | ✅ |
| Getting Started -> index | /start/setup-channel | ✅ |
| Getting started -> Sampler | /run/primitives-get-started | ✅ |
| Getting started -> Estimator | /run/primitives-get-started | ✅ |
| backend.run | /api/migration-guides/qiskit-runtime | ✅ |
| intro to primtivies | /run/primitives | ✅ |
| intro to sessions | /run/sessions | ✅ |
Tutorials ✅
| original | redirect | status |
|---|---|---|
| Get started with estimator | /run/primitives-get-started | ✅ (duplicate of Get Started) |
| Get started with sampler | /run/primitives-get-started | ✅ (duplicate of Get Started) |
| Error suppression and error mitigation | /run/configure-error-mitigation | ✅ |
| CHSH with estimator | https://learning.quantum-computing.ibm.com/tutorial/chsh-inequality | ✅ |
| VQE with estimator | https://learning.quantum-computing.ibm.com/tutorial/variational-quantum-eigensolver | ✅ |
| Grover with Sampler | https://learning.quantum-computing.ibm.com/tutorial/grovers-algorithm | ✅ |
| QAOA with Primitives | https://learning.quantum-computing.ibm.com/tutorial/quantum-approximate-optimization-algorithm | ✅ |
| Submit user-transpiled circuits using primitives | /transpile | ✅ |
| All Tutorials (index) | https://learning.quantum-computing.ibm.com/catalog/tutorials | ✅ |
How to ✅
| original | redirect | status |
|---|---|---|
| Run primitive in a session | /run/run-jobs-in-session | ✅ |
| Run on quantum backends | /run/get-backend-information | ✅ |
| Retrieve job results | /run/monitor-job | ✅ |
| Configure primitive options | /run/advanced-runtime-options | ✅ |
| Configure error mitigation options | /run/configure-error-mitigation | ✅ |
| Configure error suppression | /run/configure-runtime-compilation | ✅ |
| Manage your account | /start/setup-channel | ✅ |
| Noisy simulators | /verify/using-ibm-quantum-simulators | ✅ |
Migrate ✅
| original | redirect | status |
|---|---|---|
| Migrate to using Qiskit Runtime | /api/migration-guides/qiskit-runtime | ✅ |
| Migrate setup from qiskit-ibmq-provider | /api/migration-guides/qiskit-runtime | ✅ |
| Use Estimator to design an algorithm | /api/migration-guides/qiskit-runtime-examples | ✅ |
| Use Sampler to design an algorithm | /api/migration-guides/qiskit-runtime-examples | ✅ |
| Update parameter values | /verify/simulate-with-qiskit-primitives#parameterized-circuit-with-estimator | ✅ |
| Algorithm tuning options | /run/advanced-runtime-options | ✅ |
| migrate/backend_run_migration_guide | /api/migration-guides/qiskit-runtime-from-provider | ✅ |
Work with Qiskit Runtime in IBM Cloud ✅
Reference ✅
| original | redirect | status |
|---|---|---|
| API error codes | /errors | ✅ |
| FAQs -> index | /support | ✅ |
| FAQS -> different between open source | /run/primitives | ✅ |
| FAQS -> max execution time | /run/max-execution-time | ✅ |
| Retired systems | /run/retired-systems | ✅ |
| Release notes | /api/qiskit-ibm-runtime/release-notes | ✅ |
API docs themselves. Special case ibm-runtime.html and ibm_runtime.html. ✅
Translations ✅
Should redirect to English for now. Make sure we account for them with every URL. Japanese and Spanish.
No fallback redirect ✅
Same reason as Qiskit
Qiskit.org 🚢
| original | redirect | status |
|---|---|---|
| /providers | https://qiskit.github.io/ecosystem/#providers | 🚢 |
| /ecosystem | https://qiskit.github.io/ecosystem | 🚢 |
| / (index) | http://ibm.com/quantum/qiskit | 🚢 |
No fallback redirect.
Learn
/learn (index): https://learning.quantum-computing.ibm.com
/learn URLs, which are from the qiskit.org repo for course overview pages and summer school. These should all go to GitHub (textbook or Platypus) for the relevant course.
| original | redirect | status |
|---|---|---|
| /summer-school/introduction-to-quantum-computing-and-quantum-hardware-2020 | ||
| /summer-school/quantum-computing-and-quantum-learning-2021 | ||
| /summer-school/quantum-simulation-summer-school-2022 | ||
| /course/games-and-demos | ||
| /course/introduction-course | ||
| /course/legacy-content | ||
| /course/machine-learning-course | ||
| /course/multiple-qubits-and-entanglement | ||
| /course/prerequisites | ||
| /course/quantum-algorithms-for-applications | ||
| /course/quantum-computing-labs | ||
| /course/quantum-hardware-circuits | ||
| /course/quantum-hardware-pulses | ||
| /course/quantum-protocols-and-quantum-algorithms | ||
| /course/quantum-states-and-qubits | ||
| wildcard, i.e. anything elese |
learn.qiskit.org folders, which come from Platypus:
| original | redirect | status |
|---|---|---|
qiskit.org/textbook. Should immediately redirect to their textbook folder.
| original | redirect | status |
|---|---|---|
| /algorithms |
How do we want to have translations?
These should probably handle translations by going to the GitHub link? But do we need to check that every tutorial exists? Maybe simply take you to the language folder? It looks like Japanese is our only course where translations are on the site?