Fix Qiskit broken cross-references (#3968)

arnaucasau · web-flow · commit 650eace79ffa · 2025-09-26T08:35:14.000Z
This PR fixes four broken cross-references in the Qiskit 2.2 `circuit_classical` page, and in the 1.1 & 2.1 release notes. Given that this change impacts some unsupported versions of Qiskit, we can't open a PR in the Qiskit repo to apply all the changes (see Qiskit/qiskit#15078 and Qiskit/qiskit#15080). Instead, I manually fixed the HTML files in the Box artifacts and re-gerenerated the docs. The only changes that can be synced into Qiskit/qiskit is from the `circuit_classical` page ([PR](Qiskit/qiskit#15079)) This change is important to avoid any potential issue with translations
diff --git a/docs/api/qiskit/circuit_classical.mdx b/docs/api/qiskit/circuit_classical.mdx
@@ -814,7 +814,7 @@ Similarly, the binary operations and relations have helper functions defined.
 <Function id="qiskit.circuit.classical.expr.div" github="https://github.com/Qiskit/qiskit/tree/stable/2.2/qiskit/circuit/classical/expr/constructors.py#L699-L764" signature="qiskit.circuit.classical.expr.div(left, right)">
   Create a division expression node from the given values, resolving any implicit casts and lifting the values into [`Value`](#qiskit.circuit.classical.expr.Value "qiskit.circuit.classical.expr.Value") nodes if required.
 
-  This can be used to divide numeric operands of the same type kind, to divide a :class\`\~.types.Duration\` operand by a numeric operand, or to divide two :class\`\~.types.Duration\` operands which yields an expression of type [`Float`](#qiskit.circuit.classical.types.Float "qiskit.circuit.classical.types.Float").
+  This can be used to divide numeric operands of the same type kind, to divide a [`Duration`](#qiskit.circuit.classical.types.Duration) operand by a numeric operand, or to divide two [`Duration`](#qiskit.circuit.classical.types.Duration) operands which yields an expression of type [`Float`](#qiskit.circuit.classical.types.Float "qiskit.circuit.classical.types.Float").
 
   **Examples**
 
diff --git a/docs/api/qiskit/release-notes/1.1.mdx b/docs/api/qiskit/release-notes/1.1.mdx
@@ -98,7 +98,7 @@ The Qiskit 1.1.0 release is a minor feature release that includes a myriad of ne
 >
 > *   The default two qubit synthesis methods that are used internally by the transpiler in the [`UnitarySynthesis`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") pass have been re-implemented in Rust. This yields significant runtime speedups when decomposing two qubit unitary matrices. As a consequence, the runtime of transpilation with optimization level 3 was significantly improved where running [`UnitarySynthesis`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") incurred a large runtime overhead historically. This release also starts running [`UnitarySynthesis`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") as part of the optimization stage in optimization level 2 because of these runtime performance improvements.
 >
->     Additionally, the numeric methods used in [`Isometry`](/docs/api/qiskit/1.1/qiskit.circuit.library.Isometry "qiskit.circuit.library.Isometry") have been moved to Rust, enabling large runtime speed-ups in particular for controlled unitary gate synthesis. The decomposition for multi-controlled :class:.XGate\` and [`PhaseGate`](/docs/api/qiskit/1.1/qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate") has been improved resulting in a reduction in the number of gates used in the synthesis by more than two orders of magnitude.
+>     Additionally, the numeric methods used in [`Isometry`](/docs/api/qiskit/1.1/qiskit.circuit.library.Isometry "qiskit.circuit.library.Isometry") have been moved to Rust, enabling large runtime speed-ups in particular for controlled unitary gate synthesis. The decomposition for multi-controlled [`XGate`](/docs/api/qiskit/1.1/qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") and [`PhaseGate`](/docs/api/qiskit/1.1/qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate") has been improved resulting in a reduction in the number of gates used in the synthesis by more than two orders of magnitude.
 >
 > *   A number of new transpiler passes have been introduced to Qiskit that yield significant runtime speedups while also decreasing the size of the transpiled quantum circuits in many cases. Specifically, [`ElidePermutations`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.ElidePermutations "qiskit.transpiler.passes.ElidePermutations") and [`StarPreRouting`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.StarPreRouting "qiskit.transpiler.passes.StarPreRouting") have been demonstrated to have a significant impact on the routing output quality and runtime and [`RemoveFinalReset`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.RemoveFinalReset "qiskit.transpiler.passes.RemoveFinalReset") can improve quantum circuits that include resets.
 >
diff --git a/docs/api/qiskit/release-notes/2.1.mdx b/docs/api/qiskit/release-notes/2.1.mdx
@@ -305,7 +305,7 @@ For more details about the above and much more, please see the release notes bel
 
 ### Primitives Features
 
-*   Estimator PUBs used as the input to [`BaseEstimatorV2.run()`](/docs/api/qiskit/2.1/qiskit.primitives.BaseEstimatorV2#run "qiskit.primitives.BaseEstimatorV2.run") can now be defined using [`SparseObservable`](/docs/api/qiskit/2.1/qiskit.quantum_info.SparseObservable "qiskit.quantum_info.SparseObservable") objects for the observable component of the PUB. This is in addition to the existing supported types of: `str`, [`Pauli`](/docs/api/qiskit/2.1/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli"), [`SparsePauliOp`](/docs/api/qiskit/2.1/qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"), and a mapping of `str` or :class\`\~qiskit.quantum\_info.Pauli\` to `float` values. However, if the [`SparseObservable`](/docs/api/qiskit/2.1/qiskit.quantum_info.SparseObservable "qiskit.quantum_info.SparseObservable") contains projectors, support for handling that depends on the primitive implementation. As of this release the implementations in Qiskit ([`StatevectorEstimator`](/docs/api/qiskit/2.1/qiskit.primitives.StatevectorEstimator "qiskit.primitives.StatevectorEstimator") and [`BackendEstimatorV2`](/docs/api/qiskit/2.1/qiskit.primitives.BackendEstimatorV2 "qiskit.primitives.BackendEstimatorV2")), `qiskit-ibm-runtime` ([`qiskit_ibm_runtime.EstimatorV2`](/docs/api/qiskit-ibm-runtime/estimator-v2 "(in Qiskit Runtime IBM Client)")), and Qiskit Aer’s ([`qiskit_aer.primitives.EstimatorV2`](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.primitives.EstimatorV2.html#qiskit_aer.primitives.EstimatorV2 "(in Qiskit Aer v0.17.1)")) primitive implementations do no support projective observables yet. Projective observables are those that contain the terms: `0`, `1`, `+`, `-`, `r`, or `l`.
+*   Estimator PUBs used as the input to [`BaseEstimatorV2.run()`](/docs/api/qiskit/2.1/qiskit.primitives.BaseEstimatorV2#run "qiskit.primitives.BaseEstimatorV2.run") can now be defined using [`SparseObservable`](/docs/api/qiskit/2.1/qiskit.quantum_info.SparseObservable "qiskit.quantum_info.SparseObservable") objects for the observable component of the PUB. This is in addition to the existing supported types of: `str`, [`Pauli`](/docs/api/qiskit/2.1/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli"), [`SparsePauliOp`](/docs/api/qiskit/2.1/qiskit.quantum_info.SparsePauliOp "qiskit.quantum_info.SparsePauliOp"), and a mapping of `str` or [`Pauli`](/docs/api/qiskit/2.1/qiskit.quantum_info.Pauli "qiskit.quantum_info.Pauli") to `float` values. However, if the [`SparseObservable`](/docs/api/qiskit/2.1/qiskit.quantum_info.SparseObservable "qiskit.quantum_info.SparseObservable") contains projectors, support for handling that depends on the primitive implementation. As of this release the implementations in Qiskit ([`StatevectorEstimator`](/docs/api/qiskit/2.1/qiskit.primitives.StatevectorEstimator "qiskit.primitives.StatevectorEstimator") and [`BackendEstimatorV2`](/docs/api/qiskit/2.1/qiskit.primitives.BackendEstimatorV2 "qiskit.primitives.BackendEstimatorV2")), `qiskit-ibm-runtime` ([`qiskit_ibm_runtime.EstimatorV2`](/docs/api/qiskit-ibm-runtime/estimator-v2 "(in Qiskit Runtime IBM Client)")), and Qiskit Aer’s ([`qiskit_aer.primitives.EstimatorV2`](https://qiskit.github.io/qiskit-aer/stubs/qiskit_aer.primitives.EstimatorV2.html#qiskit_aer.primitives.EstimatorV2 "(in Qiskit Aer v0.17.1)")) primitive implementations do no support projective observables yet. Projective observables are those that contain the terms: `0`, `1`, `+`, `-`, `r`, or `l`.
 
 *   Add support to the [`DataBin`](/docs/api/qiskit/2.1/qiskit.primitives.DataBin "qiskit.primitives.DataBin") class to make it serializable with [`pickle`](https://docs.python.org/3/library/pickle.html#module-pickle "(in Python v3.13)"). This enables making the [`PrimitiveJob`](/docs/api/qiskit/2.1/qiskit.primitives.PrimitiveJob "qiskit.primitives.PrimitiveJob") and [`PrimitiveResult`](/docs/api/qiskit/2.1/qiskit.primitives.PrimitiveResult "qiskit.primitives.PrimitiveResult") class serializable with [`pickle`](https://docs.python.org/3/library/pickle.html#module-pickle "(in Python v3.13)") as well.
 

Original file line number	Diff line number	Diff line change
`@@ -98,7 +98,7 @@ The Qiskit 1.1.0 release is a minor feature release that includes a myriad of ne`
`98`	`98`	`>`
`99`	`99`	> * The default two qubit synthesis methods that are used internally by the transpiler in the [`UnitarySynthesis`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") pass have been re-implemented in Rust. This yields significant runtime speedups when decomposing two qubit unitary matrices. As a consequence, the runtime of transpilation with optimization level 3 was significantly improved where running [`UnitarySynthesis`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") incurred a large runtime overhead historically. This release also starts running [`UnitarySynthesis`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.UnitarySynthesis "qiskit.transpiler.passes.UnitarySynthesis") as part of the optimization stage in optimization level 2 because of these runtime performance improvements.
`100`	`100`	`>`
`101`		-> Additionally, the numeric methods used in [`Isometry`](/docs/api/qiskit/1.1/qiskit.circuit.library.Isometry "qiskit.circuit.library.Isometry") have been moved to Rust, enabling large runtime speed-ups in particular for controlled unitary gate synthesis. The decomposition for multi-controlled :class:.XGate\` and [`PhaseGate`](/docs/api/qiskit/1.1/qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate") has been improved resulting in a reduction in the number of gates used in the synthesis by more than two orders of magnitude.
	`101`	+> Additionally, the numeric methods used in [`Isometry`](/docs/api/qiskit/1.1/qiskit.circuit.library.Isometry "qiskit.circuit.library.Isometry") have been moved to Rust, enabling large runtime speed-ups in particular for controlled unitary gate synthesis. The decomposition for multi-controlled [`XGate`](/docs/api/qiskit/1.1/qiskit.circuit.library.XGate "qiskit.circuit.library.XGate") and [`PhaseGate`](/docs/api/qiskit/1.1/qiskit.circuit.library.PhaseGate "qiskit.circuit.library.PhaseGate") has been improved resulting in a reduction in the number of gates used in the synthesis by more than two orders of magnitude.
`102`	`102`	`>`
`103`	`103`	> * A number of new transpiler passes have been introduced to Qiskit that yield significant runtime speedups while also decreasing the size of the transpiled quantum circuits in many cases. Specifically, [`ElidePermutations`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.ElidePermutations "qiskit.transpiler.passes.ElidePermutations") and [`StarPreRouting`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.StarPreRouting "qiskit.transpiler.passes.StarPreRouting") have been demonstrated to have a significant impact on the routing output quality and runtime and [`RemoveFinalReset`](/docs/api/qiskit/1.1/qiskit.transpiler.passes.RemoveFinalReset "qiskit.transpiler.passes.RemoveFinalReset") can improve quantum circuits that include resets.
`104`	`104`	`>`