From 4381020d9af8897eaf983dbc376a74d75773b0be Mon Sep 17 00:00:00 2001 From: Frank Harkins Date: Fri, 26 Jan 2024 15:33:32 +0000 Subject: [PATCH] Add headers for exceptions (#713) Quick fix to use the same logic for functions and exceptions. Closes #712. A known problem with this implementation is that some headings should not be `h3`, but it depends on the page. See https://github.com/Qiskit/documentation/issues/714. --- docs/api/qiskit/algorithms.md | 2 + docs/api/qiskit/circuit.md | 2 + docs/api/qiskit/dagcircuit.md | 4 ++ docs/api/qiskit/exceptions.md | 8 ++++ docs/api/qiskit/extensions.md | 2 + docs/api/qiskit/opflow.md | 2 + docs/api/qiskit/passmanager.md | 2 + docs/api/qiskit/providers.md | 10 +++++ docs/api/qiskit/pulse.md | 10 +++++ docs/api/qiskit/qasm2.md | 6 +++ docs/api/qiskit/qasm3.md | 4 ++ docs/api/qiskit/qpy.md | 2 + docs/api/qiskit/transpiler.md | 8 ++++ docs/api/qiskit/visualization.md | 2 + scripts/lib/api/processHtml.test.ts | 61 +++++++++++++++++++++++++++++ scripts/lib/api/processHtml.ts | 19 ++++----- 16 files changed, 132 insertions(+), 12 deletions(-) diff --git a/docs/api/qiskit/algorithms.md b/docs/api/qiskit/algorithms.md index a3abc9e0bea..0df1ac10953 100644 --- a/docs/api/qiskit/algorithms.md +++ b/docs/api/qiskit/algorithms.md @@ -193,6 +193,8 @@ Algorithms that compute the fidelity of pairs of quantum states. ### Exceptions +### AlgorithmError + `qiskit.algorithms.AlgorithmError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/algorithms/exceptions.py "view source code") diff --git a/docs/api/qiskit/circuit.md b/docs/api/qiskit/circuit.md index 09defacbac5..b21443b5678 100644 --- a/docs/api/qiskit/circuit.md +++ b/docs/api/qiskit/circuit.md @@ -344,6 +344,8 @@ constructed circuit Almost all circuit functions and methods will raise a [`CircuitError`](#qiskit.circuit.CircuitError "qiskit.circuit.CircuitError") when encountering an error that is particular to usage of Qiskit (as opposed to regular typing or indexing problems, which will typically raise the corresponding standard Python error). +### CircuitError + `qiskit.circuit.CircuitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/circuit/exceptions.py "view source code") diff --git a/docs/api/qiskit/dagcircuit.md b/docs/api/qiskit/dagcircuit.md index 1996e105bed..c8c7edd1531 100644 --- a/docs/api/qiskit/dagcircuit.md +++ b/docs/api/qiskit/dagcircuit.md @@ -32,6 +32,8 @@ python_api_name: qiskit.dagcircuit ## Exceptions +### DAGCircuitError + `qiskit.dagcircuit.DAGCircuitError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/dagcircuit/exceptions.py "view source code") @@ -40,6 +42,8 @@ Base class for errors raised by the DAGCircuit object. Set the error message. +### DAGDependencyError + `qiskit.dagcircuit.DAGDependencyError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/dagcircuit/exceptions.py "view source code") diff --git a/docs/api/qiskit/exceptions.md b/docs/api/qiskit/exceptions.md index 785eac2d2d0..75f0f6a127d 100644 --- a/docs/api/qiskit/exceptions.md +++ b/docs/api/qiskit/exceptions.md @@ -20,6 +20,8 @@ python_api_name: qiskit.exceptions All Qiskit-related errors raised by Qiskit are subclasses of the base: +### QiskitError + `qiskit.exceptions.QiskitError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/exceptions.py "view source code") @@ -36,6 +38,8 @@ Many of the Qiskit subpackages define their own more granular error, to help in Qiskit has several optional features that depend on other packages that are not required for a minimal install. You can read more about those, and ways to check for their presence, in [`qiskit.utils.optionals`](utils#module-qiskit.utils.optionals "qiskit.utils.optionals"). Trying to use a feature that requires an optional extra will raise a particular error, which subclasses both [`QiskitError`](#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") and the Python built-in `ImportError`. +### MissingOptionalLibraryError + `qiskit.exceptions.MissingOptionalLibraryError(libname, name, pip_install=None, msg=None)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/exceptions.py "view source code") @@ -46,6 +50,8 @@ Set the error message. :param libname: Name of missing library :param name: Name Two more uncommon errors relate to failures in reading user-configuration files, or specifying a filename that cannot be used: +### QiskitUserConfigError + `qiskit.exceptions.QiskitUserConfigError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/exceptions.py "view source code") @@ -54,6 +60,8 @@ Raised when an error is encountered reading a user config file. Set the error message. +### InvalidFileError + `qiskit.exceptions.InvalidFileError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/exceptions.py "view source code") diff --git a/docs/api/qiskit/extensions.md b/docs/api/qiskit/extensions.md index 6f4fc24cadb..b5cc42e1b05 100644 --- a/docs/api/qiskit/extensions.md +++ b/docs/api/qiskit/extensions.md @@ -34,6 +34,8 @@ python_api_name: qiskit.extensions The additional gates in this module will tend to raise a custom exception when they encounter problems. +### ExtensionError + `qiskit.extensions.ExtensionError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/extensions/exceptions.py "view source code") diff --git a/docs/api/qiskit/opflow.md b/docs/api/qiskit/opflow.md index d0bb7213e6e..00e79515761 100644 --- a/docs/api/qiskit/opflow.md +++ b/docs/api/qiskit/opflow.md @@ -198,6 +198,8 @@ the double commutator ## Exceptions +### OpflowError + `qiskit.opflow.OpflowError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/opflow/exceptions.py "view source code") diff --git a/docs/api/qiskit/passmanager.md b/docs/api/qiskit/passmanager.md index 113721adaa3..a2eb80c1741 100644 --- a/docs/api/qiskit/passmanager.md +++ b/docs/api/qiskit/passmanager.md @@ -161,6 +161,8 @@ With the pass manager framework, a developer can flexibly customize the optimiza ### Exceptions +### PassManagerError + `qiskit.passmanager.PassManagerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/passmanager/exceptions.py "view source code") diff --git a/docs/api/qiskit/providers.md b/docs/api/qiskit/providers.md index b7e55f9a7b4..96f745f9479 100644 --- a/docs/api/qiskit/providers.md +++ b/docs/api/qiskit/providers.md @@ -75,6 +75,8 @@ It’s worth pointing out that Terra’s version support policy doesn’t mean p ### Exceptions +### QiskitBackendNotFoundError + `qiskit.providers.QiskitBackendNotFoundError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/providers/exceptions.py "view source code") @@ -83,6 +85,8 @@ Base class for errors raised while looking for a backend. Set the error message. +### BackendPropertyError + `qiskit.providers.BackendPropertyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/providers/exceptions.py "view source code") @@ -91,6 +95,8 @@ Base class for errors raised while looking for a backend property. Set the error message. +### JobError + `qiskit.providers.JobError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/providers/exceptions.py "view source code") @@ -99,6 +105,8 @@ Base class for errors raised by Jobs. Set the error message. +### JobTimeoutError + `qiskit.providers.JobTimeoutError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/providers/exceptions.py "view source code") @@ -107,6 +115,8 @@ Base class for timeout errors raised by jobs. Set the error message. +### BackendConfigurationError + `qiskit.providers.BackendConfigurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/providers/exceptions.py "view source code") diff --git a/docs/api/qiskit/pulse.md b/docs/api/qiskit/pulse.md index fce81f9817b..7ac600f754f 100644 --- a/docs/api/qiskit/pulse.md +++ b/docs/api/qiskit/pulse.md @@ -2897,6 +2897,8 @@ The number of samples for the time to elapse ## Exceptions +### PulseError + `qiskit.pulse.PulseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/pulse/exceptions.py "view source code") @@ -2905,6 +2907,8 @@ Errors raised by the pulse module. Set the error message. +### BackendNotSet + `qiskit.pulse.BackendNotSet(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/pulse/exceptions.py "view source code") @@ -2913,6 +2917,8 @@ Raised if the builder context does not have a backend. Set the error message. +### NoActiveBuilder + `qiskit.pulse.NoActiveBuilder(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/pulse/exceptions.py "view source code") @@ -2921,6 +2927,8 @@ Raised if no builder context is active. Set the error message. +### UnassignedDurationError + `qiskit.pulse.UnassignedDurationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/pulse/exceptions.py "view source code") @@ -2929,6 +2937,8 @@ Raised if instruction duration is unassigned. Set the error message. +### UnassignedReferenceError + `qiskit.pulse.UnassignedReferenceError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/pulse/exceptions.py "view source code") diff --git a/docs/api/qiskit/qasm2.md b/docs/api/qiskit/qasm2.md index b3d3bae8ef5..83dc3a58f5d 100644 --- a/docs/api/qiskit/qasm2.md +++ b/docs/api/qiskit/qasm2.md @@ -170,6 +170,8 @@ An OpenQASM 2 string representing the circuit. This module defines a generic error type that derives from [`QiskitError`](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") that can be used as a catch when you care about failures emitted by the interoperation layer specifically. +### QASM2Error + `qiskit.qasm2.QASM2Error(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/qasm2/exceptions.py "view source code") @@ -180,6 +182,8 @@ Set the error message. In cases where the lexer or parser fails due to an invalid OpenQASM 2 file, the conversion functions will raise a more specific error with a message explaining what the failure is, and where in the file it occurred. +### QASM2ParseError + `qiskit.qasm2.QASM2ParseError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/qasm2/exceptions.py "view source code") @@ -190,6 +194,8 @@ Set the error message. When the exporters fail to export a circuit, likely because it has structure that cannot be represented by OpenQASM 2.0, they will also emit a custom error. +### QASM2ExportError + `qiskit.qasm2.QASM2ExportError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/qasm2/exceptions.py "view source code") diff --git a/docs/api/qiskit/qasm3.md b/docs/api/qiskit/qasm3.md index 2fd7561d2d3..a8f4298a818 100644 --- a/docs/api/qiskit/qasm3.md +++ b/docs/api/qiskit/qasm3.md @@ -113,6 +113,8 @@ Convert the circuit to OpenQASM 3, returning the result as a string. All of these interfaces will raise [`QASM3ExporterError`](#qiskit.qasm3.QASM3ExporterError "qiskit.qasm3.QASM3ExporterError") on failure. +### QASM3ExporterError + `qiskit.qasm3.QASM3ExporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/qasm3/exceptions.py "view source code") @@ -234,6 +236,8 @@ a circuit representation of the OpenQASM 3 program. Both of these two functions raise [`QASM3ImporterError`](#qiskit.qasm3.QASM3ImporterError "qiskit.qasm3.QASM3ImporterError") on failure. +### QASM3ImporterError + `qiskit.qasm3.QASM3ImporterError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/qasm3/exceptions.py "view source code") diff --git a/docs/api/qiskit/qpy.md b/docs/api/qiskit/qpy.md index 7f722e95305..1d6392af0e8 100644 --- a/docs/api/qiskit/qpy.md +++ b/docs/api/qiskit/qpy.md @@ -156,6 +156,8 @@ Which will save the qpy serialized circuit to the provided file. These functions will raise a custom subclass of [`QiskitError`](exceptions#qiskit.exceptions.QiskitError "qiskit.exceptions.QiskitError") if they encounter problems during serialization or deserialization. +### QpyError + `qiskit.qpy.QpyError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/qpy/exceptions.py "view source code") diff --git a/docs/api/qiskit/transpiler.md b/docs/api/qiskit/transpiler.md index 413c3e2832a..7449fb9f625 100644 --- a/docs/api/qiskit/transpiler.md +++ b/docs/api/qiskit/transpiler.md @@ -938,6 +938,8 @@ See [https://arxiv.org/abs/2102.01682](https://arxiv.org/abs/2102.01682) for mor ### Exceptions +### TranspilerError + `qiskit.transpiler.TranspilerError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/transpiler/exceptions.py "view source code") @@ -946,6 +948,8 @@ Exceptions raised during transpilation. Set the error message. +### TranspilerAccessError + `qiskit.transpiler.TranspilerAccessError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/transpiler/exceptions.py "view source code") @@ -954,6 +958,8 @@ DEPRECATED: Exception of access error in the transpiler passes. Set the error message. +### CouplingError + `qiskit.transpiler.CouplingError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/transpiler/exceptions.py "view source code") @@ -962,6 +968,8 @@ Base class for errors raised by the coupling graph object. Set the error message. +### LayoutError + `qiskit.transpiler.LayoutError(*msg)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/transpiler/exceptions.py "view source code") diff --git a/docs/api/qiskit/visualization.md b/docs/api/qiskit/visualization.md index 6eaae07ff22..c15ee16ec3e 100644 --- a/docs/api/qiskit/visualization.md +++ b/docs/api/qiskit/visualization.md @@ -233,6 +233,8 @@ You can find code examples for each visualization functions on the individual fu ## Exceptions +### VisualizationError + `qiskit.visualization.VisualizationError(*message)`[GitHub](https://github.com/qiskit/qiskit/tree/stable/0.45/qiskit/visualization/exceptions.py "view source code") diff --git a/scripts/lib/api/processHtml.test.ts b/scripts/lib/api/processHtml.test.ts index 7bf1275c871..b74812cd56a 100644 --- a/scripts/lib/api/processHtml.test.ts +++ b/scripts/lib/api/processHtml.test.ts @@ -429,4 +429,65 @@ backends may not have this attribute.

apiName: "qiskit_ibm_provider.least_busy", }); }); + + test("exception with added heading", () => { + const html = `
+

Top-level exceptions (qiskit.exceptions)

+

All Qiskit-related errors raised by Qiskit are subclasses of the base:

+
+
+exception qiskit.exceptions.QiskitError(*message)[source]
+

Base class for errors raised by Qiskit.

+

Set the error message.

+
+ +
+

Note

+

Errors that are just general programming errors, such as incorrect typing, may still raise +standard Python errors such as TypeError. QiskitError is generally for errors raised +in usage that is particular to Qiskit.

+
+

Many of the Qiskit subpackages define their own more granular error, to help in catching only the +subset of errors you care about. For example, qiskit.circuit almost exclusively uses +CircuitError, while both QASM2ExportError and QASM2ParseError derive from +QASM2Error in qiskit.qasm2, which is in turn a type of QiskitError.

+

Qiskit has several optional features that depend on other packages that are not required for a +minimal install. You can read more about those, and ways to check for their presence, in +qiskit.utils.optionals. Trying to use a feature that requires an optional extra will raise a +particular error, which subclasses both QiskitError and the Python built-in ImportError.

+
+`; + const doc = Doc.load(html); + const meta: Metadata = {}; + processMembersAndSetMeta(doc.$, doc.$main, meta); + doc.expectHtml(`
+

Top-level exceptions (qiskit.exceptions)

+

All Qiskit-related errors raised by Qiskit are subclasses of the base:

+

QiskitError

+qiskit.exceptions.QiskitError(*message)GitHub

+

Base class for errors raised by Qiskit.

+

Set the error message.

+
+ +
+

Note

+

Errors that are just general programming errors, such as incorrect typing, may still raise +standard Python errors such as TypeError. QiskitError is generally for errors raised +in usage that is particular to Qiskit.

+
+

Many of the Qiskit subpackages define their own more granular error, to help in catching only the +subset of errors you care about. For example, qiskit.circuit almost exclusively uses +CircuitError, while both QASM2ExportError and QASM2ParseError derive from +QASM2Error in qiskit.qasm2, which is in turn a type of QiskitError.

+

Qiskit has several optional features that depend on other packages that are not required for a +minimal install. You can read more about those, and ways to check for their presence, in +qiskit.utils.optionals. Trying to use a feature that requires an optional extra will raise a +particular error, which subclasses both QiskitError and the Python built-in ImportError.

+
+`); + expect(meta).toEqual({ + apiName: "qiskit.exceptions.QiskitError", + apiType: "exception", + }); + }); }); diff --git a/scripts/lib/api/processHtml.ts b/scripts/lib/api/processHtml.ts index cc9dcd37076..faca240b642 100644 --- a/scripts/lib/api/processHtml.ts +++ b/scripts/lib/api/processHtml.ts @@ -357,23 +357,18 @@ export function processMembersAndSetMeta( return output.join("\n"); } - if (apiType === "function") { - findByText($, $main, "em.property", "function").remove(); - const funcDescription = `

${$child.html()}${github}

`; + if (apiType === "function" || apiType === "exception") { + findByText($, $main, "em.property", apiType).remove(); + const descriptionHtml = `

${$child.html()}${github}

`; const pageHeading = $dl.siblings("h1").text(); if (id.endsWith(pageHeading) && pageHeading != "") { - // Page is already dedicated to function; no heading needed - return funcDescription; + // Page is already dedicated to apiType; no heading needed + return descriptionHtml; } - const funcName = id.split(".").slice(-1)[0]; - return `

${funcName}

${funcDescription}`; - } - - if (apiType === "exception") { - findByText($, $main, "em.property", "exception").remove(); - return `

${$child.html()}${github}

`; + const apiName = id.split(".").slice(-1)[0]; + return `

${apiName}

${descriptionHtml}`; } throw new Error(`Unhandled Python type: ${apiType}`);