Tidy up pytket.circuit API docs (#1178)

* don't clutter pytket.circuit docs by expanding submodules

* change caption

* use bysource order for autodoc

* start using automethod for Circuit methods

* fix typo

* use autodoc typehints

* Expand TOC for all pages

* add some circuit properties

* delete unused config settings

* add another chunk of automethod boilerplate

* finish adding circuit methods

* add some notes on Circuit.add_gate

* submodules -> classes

* scrub ._tket from pytket.circuit docs source

* remove more _tket

* don't use sphinx_autodoc_typehints for now

* remove non-existent Reset method

* use submodules rather than classes

* don't show binary info in pytket.circuit doc

* remove typehints extension entirely

* remove duplicate CV method

* remove more duplicate methods

* submodules -> classes

* reorder circuit properties

* remove duplicate properties

* remove :special-members: and use automethod for __init__ etc

* remove __hash__

* minor spacing edit

* Revert "minor spacing edit"

This reverts commit abe76a4.

* add missing methods found by python script

* use autoproperty for created_qubits and discarded_qubits

* add script to check circuit methods and properties

* fix typo

* remove comment

* fix spaxing and heading

* consistent headings

* remove some dunder methods from API docs

* add __rshift__ dunder method back into the docs

* add explanatory comments

* remove spaces

pytket/docs/check_circuit_class_docs.py

@@ -0,0 +1,16 @@
+import inspect
+import re
+
+from pytket._tket.circuit import Circuit
+
+# This script is used to check that no methods or properties of
+# the Circuit class are left out in the circuit_class.rst file.
+
+with open("circuit_class.rst", "r", encoding="utf-8") as file:
+    rst = file.read()
+
+in_methods = {p[0] for p in inspect.getmembers(Circuit)}
+pattern = re.compile(r"(?:\bautomethod\b|\bautoproperty\b):: (\w+)\n")
+in_docs = set(pattern.findall(rst))
+missing = in_methods - in_docs
+print([s for s in missing if not s.startswith("_")])

pytket/docs/circuit.rst

@@ -2,7 +2,7 @@ pytket.circuit
 ==================================
 .. toctree::
    :caption: Classes:
-   :maxdepth: 2
+   :maxdepth: 1
 
    circuit_class.rst
    optype.rst
@@ -14,106 +14,106 @@ pytket.circuit
 
 .. automodule:: pytket._tket.circuit
     :members: fresh_symbol
-.. autoclass:: pytket._tket.circuit.Op
+.. autoclass:: pytket.circuit.Op
     :members:
-.. autoclass:: pytket._tket.circuit.Command
+.. autoclass:: pytket.circuit.Command
     :members:
-.. autoclass:: pytket._tket.circuit.BasisOrder
+.. autoclass:: pytket.circuit.BasisOrder
     :members:
-.. autoclass:: pytket._tket.circuit.CXConfigType
+.. autoclass:: pytket.circuit.CXConfigType
     :members:
-.. autoclass:: pytket._tket.circuit.CircBox
+.. autoclass:: pytket.circuit.CircBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.Unitary1qBox
+.. autoclass:: pytket.circuit.Unitary1qBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.Unitary2qBox
+.. autoclass:: pytket.circuit.Unitary2qBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.Unitary3qBox
+.. autoclass:: pytket.circuit.Unitary3qBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ExpBox
+.. autoclass:: pytket.circuit.ExpBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.PauliExpBox
+.. autoclass:: pytket.circuit.PauliExpBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.PauliExpPairBox
+.. autoclass:: pytket.circuit.PauliExpPairBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ToffoliBox
+.. autoclass:: pytket.circuit.ToffoliBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.QControlBox
+.. autoclass:: pytket.circuit.QControlBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.CustomGateDef
+.. autoclass:: pytket.circuit.CustomGateDef
     :members:
-.. autoclass:: pytket._tket.circuit.CustomGate
+.. autoclass:: pytket.circuit.CustomGate
     :members:
-.. autoclass:: pytket._tket.circuit.Conditional
+.. autoclass:: pytket.circuit.Conditional
     :members:
-.. autoclass:: pytket._tket.circuit.ClassicalExpBox
+.. autoclass:: pytket.circuit.ClassicalExpBox
     :members:
-.. autoclass:: pytket._tket.circuit.PhasePolyBox
+.. autoclass:: pytket.circuit.PhasePolyBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ProjectorAssertionBox
+.. autoclass:: pytket.circuit.ProjectorAssertionBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.StabiliserAssertionBox
+.. autoclass:: pytket.circuit.StabiliserAssertionBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.WASMOp
+.. autoclass:: pytket.circuit.WASMOp
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.MultiBitOp
+.. autoclass:: pytket.circuit.MultiBitOp
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.SetBitsOp
+.. autoclass:: pytket.circuit.SetBitsOp
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ClassicalEvalOp
+.. autoclass:: pytket.circuit.ClassicalEvalOp
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ClassicalOp
+.. autoclass:: pytket.circuit.ClassicalOp
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.CopyBitsOp
+.. autoclass:: pytket.circuit.CopyBitsOp
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.RangePredicateOp
+.. autoclass:: pytket.circuit.RangePredicateOp
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.MultiplexorBox
+.. autoclass:: pytket.circuit.MultiplexorBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.MultiplexedRotationBox
+.. autoclass:: pytket.circuit.MultiplexedRotationBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.MultiplexedU2Box
+.. autoclass:: pytket.circuit.MultiplexedU2Box
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.MultiplexedTensoredU2Box
+.. autoclass:: pytket.circuit.MultiplexedTensoredU2Box
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.StatePreparationBox
+.. autoclass:: pytket.circuit.StatePreparationBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.DiagonalBox
+.. autoclass:: pytket.circuit.DiagonalBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ConjugationBox
+.. autoclass:: pytket.circuit.ConjugationBox
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ResourceBounds
+.. autoclass:: pytket.circuit.ResourceBounds
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.ResourceData
+.. autoclass:: pytket.circuit.ResourceData
     :special-members:
     :members:
-.. autoclass:: pytket._tket.circuit.DummyBox
+.. autoclass:: pytket.circuit.DummyBox
     :special-members:
     :members: