Merge pull request #58 from ColibrITD-SAS/feat-doc-abc

specify in the doc of each ABC that it should not be instantiated directly

Author: Henri-ColibrITD

CONTRIBUTING.md

@@ -125,8 +125,8 @@ following (even though each of these sections is optional):
 2. `Returns`
 3. `Raises`
 4. `Example(s)`
-5. `Notes`
-6. `Warnings`
+5. `Note`
+6. `Warning`
 
 ### When you're done
 

docs/_static/custom.js

@@ -92,12 +92,25 @@ window.onload = () => {
     });
     ngListLocation.innerHTML = ngLinks;
   }
-};
 
-// const themeButton = document.querySelector('themeSwitcher')
-// themeButton.addEventListener('click', () => {
-//
-// });
+  // we add a note for abstract classes to remind that they cannot be
+  // implemented directly
+  document.querySelectorAll(".class").forEach((class_elt) => {
+    if (isABC(class_elt)) {
+      parents = class_elt.querySelector("dd > p:first-child");
+      template = document.createElement("template");
+      template.innerHTML = `
+      <div class="admonition note">
+        <p class="admonition-title"><span class="highlighted">Note</span></p>
+        <p>
+          Abstract classes (ABCs) are not meant to be instantiated as is. See 
+          classes that inherite from this one to check how to instantiate it.
+        </p>
+      </div>`;
+      parents.insertAdjacentElement("afterend", template.content.children[0]);
+    }
+  });
+};
 
 function getEndOfClassHeader(elt) {
   admonition = elt.querySelectorAll(".admonition");
@@ -109,6 +122,11 @@ function getEndOfClassHeader(elt) {
   return elt;
 }
 
+function isABC(elt) {
+  parents = elt.querySelector("dd > p:first-child");
+  return parents && parents.innerHTML.includes("ABC");
+}
+
 function isEnum(elt, explored = []) {
   id = elt.querySelector("dt").id;
   if (explored.includes(id)) return false;

mpqp/core/instruction/gates/gate.py

@@ -335,7 +335,7 @@ def inverse(self) -> Gate:
 
 @typechecked
 class SingleQubitGate(Gate, ABC):
-    """Gates operating on a single qubit.
+    """Abstract class for gates operating on a single qubit.
 
     Args:
         target: Index or referring to the qubit on which the gate will be applied.

mpqp/core/instruction/gates/gate_definition.py

@@ -17,7 +17,7 @@
 
 @typechecked
 class GateDefinition(ABC):
-    """A class used to handle the definition of a Gate.
+    """Abstract class used to handle the definition of a Gate.
 
     A quantum gate can be defined in several ways, and this class allows us to
     define it as we prefer. It also handles the translation from one definition

mpqp/core/instruction/gates/native_gates.py

@@ -87,7 +87,7 @@ def _qiskit_parameter_adder(
 class NativeGate(Gate, SimpleClassReprABC):
     """The standard on which we rely, OpenQASM, comes with a set of gates
     supported by default. More complicated gates can be defined by the user.
-    This class represent all those gates supported by default.
+    This abstract class represent all those gates supported by default.
 
     Args:
         targets: List of indices referring to the qubits on which the gate will
@@ -102,9 +102,9 @@ class NativeGate(Gate, SimpleClassReprABC):
 class RotationGate(NativeGate, ParametrizedGate, SimpleClassReprABC):
     """Many gates can be classified as a simple rotation gate, around a specific
     axis (and potentially with a control qubit). All those gates have in common
-    a single parameter: ``theta``. This class help up factorize this behavior,
-    and simply having to tweak the matrix semantics and qasm translation of
-    the specific gate.
+    a single parameter: ``theta``. This abstract class helps up factorize this
+    behavior, and simply having to tweak the matrix semantics and qasm
+    translation of the specific gate.
 
     Args:
         theta: Angle of the rotation.
@@ -169,7 +169,7 @@ def to_other_language(
 
 @typechecked
 class NoParameterGate(NativeGate, SimpleClassReprABC):
-    """Class describing native gates that do not depend on parameters.
+    """Abstract class describing native gates that do not depend on parameters.
 
     Args:
         targets: List of indices referring to the qubits on which the gate will
@@ -255,7 +255,8 @@ def to_matrix(self) -> Matrix:
 
 @typechecked
 class OneQubitNoParamGate(SingleQubitGate, NoParameterGate, SimpleClassReprABC):
-    """Class describing one-qubit native gates that do not depend on parameters.
+    """Abstract Class describing one-qubit native gates that do not depend on
+    parameters.
 
     Args:
         target: Index referring to the qubits on which the gate will be applied.

mpqp/core/instruction/gates/parametrized_gate.py

@@ -31,8 +31,7 @@
 
 @typechecked
 class ParametrizedGate(Gate, ABC):
-    """Abstract class to factorize behavior of parametrized gate. Since it's an
-    abstract class, do not instantiate one yourself.
+    """Abstract class to factorize behavior of parametrized gate.
 
     Args:
         definition: Provide a definition of the gate (matrix, gate combination,

mpqp/core/instruction/measurement/measure.py

@@ -13,15 +13,15 @@
 from abc import ABC
 from typing import Optional
 
-from typeguard import typechecked, TypeCheckError
+from typeguard import TypeCheckError, typechecked
 
 from mpqp.core.instruction import Instruction
 
 
 @typechecked
 class Measure(Instruction, ABC):
-    """Class representing a generic measure of quantum state generated by a
-    quantum circuit.
+    """Abstract class representing the measurement of the quantum state
+    generated by a quantum circuit.
 
     This class is used to regroup attributes and methods shared by all different
     types of measures.