Set up redirects for functions moved to module pages (#10692)

* Set up redirects for functions moved to module pages

* Add exceptions from Jake's PR

* Set up conf.py

* Try full URLs for redirects

* DRY stubs/ in api_redirects.txt

* Fix typo

* Fix issues found by 404 script

docs/api_redirects.txt

@@ -0,0 +1,286 @@
+qiskit.algorithms.AlgorithmError algorithms
+qiskit.algorithms.eval_observables algorithms
+qiskit.algorithms.estimate_observables algorithms
+
+qiskit.assembler.assemble_circuits assembler
+qiskit.assembler.assemble_schedules assembler
+qiskit.assembler.disassemble assembler
+
+qiskit.circuit.random.random_circuit circuit
+
+qiskit.circuit.library.templates.nct.template_nct_2a_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_2a_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_2a_3 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_4a_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_4a_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_4a_3 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_4b_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_4b_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_5a_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_5a_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_5a_3 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_5a_4 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_6a_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_6a_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_6a_3 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_6a_4 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_6b_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_6b_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_6c_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_7a_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_7b_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_7c_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_7d_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_7e_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9a_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_3 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_4 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_5 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_6 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_7 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_8 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_9 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_10 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_11 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9c_12 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_1 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_2 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_3 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_4 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_5 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_6 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_7 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_8 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_9 circuit_library
+qiskit.circuit.library.templates.nct.template_nct_9d_10 circuit_library
+qiskit.circuit.library.clifford_2_1 circuit_library
+qiskit.circuit.library.clifford_2_2 circuit_library
+qiskit.circuit.library.clifford_2_3 circuit_library
+qiskit.circuit.library.clifford_2_4 circuit_library
+qiskit.circuit.library.clifford_3_1 circuit_library
+qiskit.circuit.library.clifford_4_1 circuit_library
+qiskit.circuit.library.clifford_4_2 circuit_library
+qiskit.circuit.library.clifford_4_3 circuit_library
+qiskit.circuit.library.clifford_4_4 circuit_library
+qiskit.circuit.library.clifford_5_1 circuit_library
+qiskit.circuit.library.clifford_6_1 circuit_library
+qiskit.circuit.library.clifford_6_2 circuit_library
+qiskit.circuit.library.clifford_6_3 circuit_library
+qiskit.circuit.library.clifford_6_4 circuit_library
+qiskit.circuit.library.clifford_6_5 circuit_library
+qiskit.circuit.library.clifford_8_1 circuit_library
+qiskit.circuit.library.clifford_8_2 circuit_library
+qiskit.circuit.library.clifford_8_3 circuit_library
+qiskit.circuit.library.rzx_yz circuit_library
+qiskit.circuit.library.rzx_xz circuit_library
+qiskit.circuit.library.rzx_cy circuit_library
+qiskit.circuit.library.rzx_zz1 circuit_library
+qiskit.circuit.library.rzx_zz2 circuit_library
+qiskit.circuit.library.rzx_zz3 circuit_library
+
+qiskit.compiler.assemble compiler
+qiskit.compiler.schedule compiler
+qiskit.compiler.transpile compiler
+qiskit.compiler.sequence compiler
+
+qiskit.converters.circuit_to_dag converters
+qiskit.converters.dag_to_circuit converters
+qiskit.converters.circuit_to_instruction converters
+qiskit.converters.circuit_to_gate converters
+qiskit.converters.ast_to_dag converters
+qiskit.converters.dagdependency_to_circuit converters
+qiskit.converters.circuit_to_dagdependency converters
+qiskit.converters.dag_to_dagdependency converters
+qiskit.converters.dagdependency_to_dag converters
+
+qiskit.dagcircuit.DAGCircuitError dagcircuit
+
+qiskit.opflow.commutator opflow
+qiskit.opflow.anti_commutator opflow
+qiskit.opflow.double_commutator opflow
+qiskit.opflow.OpflowError opflow
+
+qiskit.providers.QiskitBackendNotFoundError providers
+qiskit.providers.BackendPropertyError providers
+qiskit.providers.JobError providers
+qiskit.providers.JobTimeoutError providers
+
+qiskit.pulse.builder.build pulse
+qiskit.pulse.builder.acquire_channel pulse
+qiskit.pulse.builder.control_channels pulse
+qiskit.pulse.builder.drive_channel pulse
+qiskit.pulse.builder.measure_channel pulse
+qiskit.pulse.builder.acquire pulse
+qiskit.pulse.builder.barrier pulse
+qiskit.pulse.builder.call pulse
+qiskit.pulse.builder.delay pulse
+qiskit.pulse.builder.play pulse
+qiskit.pulse.builder.reference pulse
+qiskit.pulse.builder.set_frequency pulse
+qiskit.pulse.builder.set_phase pulse
+qiskit.pulse.builder.shift_frequency pulse
+qiskit.pulse.builder.shift_phase pulse
+qiskit.pulse.builder.snapshot pulse
+qiskit.pulse.builder.align_equispaced pulse
+qiskit.pulse.builder.align_func pulse
+qiskit.pulse.builder.align_left pulse
+qiskit.pulse.builder.align_right pulse
+qiskit.pulse.builder.align_sequential pulse
+qiskit.pulse.builder.circuit_scheduler_settings pulse
+qiskit.pulse.builder.frequency_offset pulse
+qiskit.pulse.builder.phase_offset pulse
+qiskit.pulse.builder.transpiler_settings pulse
+qiskit.pulse.builder.measure pulse
+qiskit.pulse.builder.measure_all pulse
+qiskit.pulse.builder.delay_qubits pulse
+qiskit.pulse.builder.cx pulse
+qiskit.pulse.builder.u1 pulse
+qiskit.pulse.builder.u2 pulse
+qiskit.pulse.builder.u3 pulse
+qiskit.pulse.builder.x pulse
+qiskit.pulse.builder.active_backend pulse
+qiskit.pulse.builder.active_transpiler_settings pulse
+qiskit.pulse.builder.active_circuit_scheduler_settings pulse
+qiskit.pulse.builder.num_qubits pulse
+qiskit.pulse.builder.qubit_channels pulse
+qiskit.pulse.builder.samples_to_seconds pulse
+qiskit.pulse.builder.seconds_to_samples pulse
+
+qiskit.pulse.library.constant pulse
+qiskit.pulse.library.zero pulse
+qiskit.pulse.library.square pulse
+qiskit.pulse.library.sawtooth pulse
+qiskit.pulse.library.triangle pulse
+qiskit.pulse.library.cos pulse
+qiskit.pulse.library.sin pulse
+qiskit.pulse.library.gaussian pulse
+qiskit.pulse.library.gaussian_deriv pulse
+qiskit.pulse.library.sech pulse
+qiskit.pulse.library.sech_deriv pulse
+qiskit.pulse.library.gaussian_square pulse
+qiskit.pulse.library.drag pulse
+
+qiskit.pulse.transforms.add_implicit_acquires pulse
+qiskit.pulse.transforms.align_measures pulse
+qiskit.pulse.transforms.block_to_schedule pulse
+qiskit.pulse.transforms.compress_pulses pulse
+qiskit.pulse.transforms.flatten pulse
+qiskit.pulse.transforms.inline_subroutines pulse
+qiskit.pulse.transforms.pad pulse
+qiskit.pulse.transforms.remove_directives pulse
+qiskit.pulse.transforms.remove_trivial_barriers pulse
+qiskit.pulse.transforms.block_to_dag pulse
+qiskit.pulse.transforms.target_qobj_transform pulse
+
+qiskit.qasm.Qasm qasm
+
+qiskit.qpy.load qpy
+qiskit.qpy.dump qpy
+
+qiskit.quantum_info.average_gate_fidelity quantum_info
+qiskit.quantum_info.process_fidelity quantum_info
+qiskit.quantum_info.gate_error quantum_info
+qiskit.quantum_info.diamond_norm quantum_info
+qiskit.quantum_info.state_fidelity quantum_info
+qiskit.quantum_info.purity quantum_info
+qiskit.quantum_info.concurrence quantum_info
+qiskit.quantum_info.entropy quantum_info
+qiskit.quantum_info.entanglement_of_formation quantum_info
+qiskit.quantum_info.mutual_information quantum_info
+qiskit.quantum_info.partial_trace quantum_info
+qiskit.quantum_info.shannon_entropy quantum_info
+qiskit.quantum_info.commutator quantum_info
+qiskit.quantum_info.anti_commutator quantum_info
+qiskit.quantum_info.double_commutator quantum_info
+qiskit.quantum_info.random_statevector quantum_info
+qiskit.quantum_info.random_density_matrix quantum_info
+qiskit.quantum_info.random_unitary quantum_info
+qiskit.quantum_info.random_hermitian quantum_info
+qiskit.quantum_info.random_pauli quantum_info
+qiskit.quantum_info.random_clifford quantum_info
+qiskit.quantum_info.random_quantum_channel quantum_info
+qiskit.quantum_info.random_cnotdihedral quantum_info
+qiskit.quantum_info.random_pauli_table quantum_info
+qiskit.quantum_info.random_pauli_list quantum_info
+qiskit.quantum_info.random_stabilizer_table quantum_info
+qiskit.quantum_info.hellinger_distance quantum_info
+qiskit.quantum_info.hellinger_fidelity quantum_info
+qiskit.quantum_info.two_qubit_cnot_decompose quantum_info
+qiskit.quantum_info.decompose_clifford quantum_info
+
+qiskit.result.marginal_counts result
+qiskit.result.marginal_distribution result
+qiskit.result.marginal_memory result
+qiskit.result.sampled_expectation_value result
+
+qiskit.scheduler.ScheduleConfig scheduler
+qiskit.scheduler.schedule_circuit scheduler
+qiskit.scheduler.methods.basic scheduler
+
+qiskit.synthesis.synth_cnot_count_full_pmh synthesis
+qiskit.synthesis.synth_cnot_depth_line_kms synthesis
+qiskit.synthesis.synth_cz_depth_line_mr synthesis
+qiskit.synthesis.synth_permutation_depth_lnn_kms synthesis
+qiskit.synthesis.synth_permutation_basic synthesis
+qiskit.synthesis.synth_permutation_acg synthesis
+qiskit.synthesis.synth_clifford_full synthesis
+qiskit.synthesis.synth_clifford_ag synthesis
+qiskit.synthesis.synth_clifford_bm synthesis
+qiskit.synthesis.synth_clifford_greedy synthesis
+qiskit.synthesis.synth_clifford_layers synthesis
+qiskit.synthesis.synth_clifford_depth_lnn synthesis
+qiskit.synthesis.synth_cnotdihedral_full synthesis
+qiskit.synthesis.synth_cnotdihedral_two_qubits synthesis
+qiskit.synthesis.synth_cnotdihedral_general synthesis
+qiskit.synthesis.synth_stabilizer_layers synthesis
+qiskit.synthesis.synth_stabilizer_depth_lnn synthesis
+qiskit.synthesis.generate_basic_approximations synthesis
+
+qiskit.tools.parallel_map tools
+qiskit.tools.job_monitor tools
+qiskit.tools.backend_monitor tools
+qiskit.tools.backend_overview tools
+qiskit.tools.events.TextProgressBar tools
+
+qiskit.transpiler.TranspilerError transpiler
+qiskit.transpiler.TranspilerAccessError transpiler
+
+qiskit.transpiler.preset_passmanagers.generate_preset_pass_manager transpiler_preset
+qiskit.transpiler.preset_passmanagers.level_0_pass_manager transpiler_preset
+qiskit.transpiler.preset_passmanagers.level_1_pass_manager transpiler_preset
+qiskit.transpiler.preset_passmanagers.level_2_pass_manager transpiler_preset
+qiskit.transpiler.preset_passmanagers.level_3_pass_manager transpiler_preset
+
+qiskit.transpiler.preset_passmanagers.common.generate_control_flow_options_check transpiler_preset
+qiskit.transpiler.preset_passmanagers.common.generate_error_on_control_flow transpiler_preset
+qiskit.transpiler.preset_passmanagers.common.generate_unroll_3q transpiler_preset
+qiskit.transpiler.preset_passmanagers.common.generate_embed_passmanager transpiler_preset
+qiskit.transpiler.preset_passmanagers.common.generate_routing_passmanager transpiler_preset
+qiskit.transpiler.preset_passmanagers.common.generate_pre_op_passmanager transpiler_preset
+qiskit.transpiler.preset_passmanagers.common.generate_translation_passmanager transpiler_preset
+qiskit.transpiler.preset_passmanagers.common.generate_scheduling transpiler_preset
+
+qiskit.transpiler.preset_passmanagers.plugin.list_stage_plugins transpiler_plugins
+qiskit.transpiler.preset_passmanagers.plugin.passmanager_stage_plugins transpiler_plugins
+
+qiskit.utils.add_deprecation_to_docstring utils
+qiskit.utils.deprecate_arg utils
+qiskit.utils.deprecate_arguments utils
+qiskit.utils.deprecate_func utils
+qiskit.utils.deprecate_function utils
+qiskit.utils.local_hardware_info utils
+qiskit.utils.is_main_process utils
+qiskit.utils.apply_prefix utils
+qiskit.utils.detach_prefix utils
+qiskit.utils.wrap_method utils
+qiskit.utils.summarize_circuits utils
+qiskit.utils.get_entangler_map utils
+qiskit.utils.validate_entangler_map utils
+qiskit.utils.has_ibmq utils
+qiskit.utils.has_aer utils
+qiskit.utils.name_args utils
+qiskit.utils.algorithm_globals utils
+
+qiskit.visualization.VisualizationError visualization

docs/conf.py

@@ -10,6 +10,8 @@
 # copyright notice, and modified files need to carry a notice indicating
 # that they have been altered from the originals.
 
+from __future__ import annotations
+
 # pylint: disable=invalid-name,missing-function-docstring
 
 """Sphinx documentation builder."""
@@ -18,6 +20,7 @@
 import doctest
 import os
 import subprocess
+from pathlib import Path
 
 project = "Qiskit"
 project_copyright = f"2017-{datetime.date.today().year}, Qiskit Development Team"
@@ -50,6 +53,7 @@
     "reno.sphinxext",
     "sphinx_design",
     "sphinx_remove_toctrees",
+    "sphinx_reredirects",
 ]
 
 templates_path = ["_templates"]
@@ -233,6 +237,36 @@
 
 """
 
+
+# ----------------------------------------------------------------------------------
+# Redirects
+# ----------------------------------------------------------------------------------
+
+def determine_api_redirects() -> dict[str, str]:
+    """Set up API redirects for functions that we moved to module pages.
+
+    Note that we have redirects in Cloudflare for methods moving to their class page. We
+    could not do this for functions because some functions still have dedicated
+    HTML pages, so we cannot use a generic rule.
+    """
+    lines = Path("api_redirects.txt").read_text().splitlines()
+    result = {}
+    for line in lines:
+        if not line:
+            continue
+        obj_name, new_module_page_name = line.split(" ")
+        # E.g. `../apidoc/assembler.html#qiskit.assembler.assemble_circuits
+        new_url = (
+            "https://qiskit.org/documentation/apidoc/" +
+            f"{new_module_page_name}.html#{obj_name}"
+        )
+        result[f"stubs/{obj_name}"] = new_url
+    return result
+
+
+redirects = determine_api_redirects()
+
+
 # ---------------------------------------------------------------------------------------
 # Prod changes
 # ---------------------------------------------------------------------------------------

requirements-dev.txt

@@ -35,6 +35,7 @@ Sphinx>=6.0,<7.2
 qiskit-sphinx-theme~=1.15.0
 sphinx-design>=0.2.0
 sphinx-remove-toctrees
+sphinx-reredirects
 nbsphinx~=0.9.2
 nbconvert~=7.7.1
 # TODO: switch to stable release when 4.1 is released