docs: port manual source material to MyST markdown (#370)

* port to markdown, fix jupyter-execute and jupyter-input

* fix indentation issues in backends page

* fix indentation issues in circuit page

* fix broken sphinx admonitions

* fix remaining indentation issues in Circuit construction page

* port index page to Myst Markdown

* fix cells with expected errors

* clean up compilation chapter

* clean up ZX diagrams chapter

* fixes to compiler page

* remove jupyter-sphinx dependency

* fix formatting issues found in code review

* update README

* test that C.I. fails on a dodgy cell

* remove error test from code cell

* fix gate_counts cell indentation

README.md

@@ -7,7 +7,7 @@ Pytket is a python module for interfacing with tket, a quantum computing toolkit
 
 This repository contains the pytket user manual and example notebooks content in the `docs` directory. It does not contain source code for pytket itself. The source code is maintained on the [tket repository](https://github.com/CQCL/tket).
 
-The manual and examples are built and deployed as html pages using the [jupyter-sphinx](https://jupyter-sphinx.readthedocs.io/en/latest/) and [myst-nb](https://myst-nb.readthedocs.io/en/latest/) libraries. Instructions on building the docs locally can be found [here](https://github.com/CQCL/pytket-docs/blob/main/docs/README.md).
+The manual and examples are built and deployed as html pages using the [myst-nb](https://myst-nb.readthedocs.io/en/latest/) library. Instructions on building the docs locally can be found [here](https://github.com/CQCL/pytket-docs/blob/main/docs/README.md).
 
 Note that the TKET website is not deployed from this repository. This repository just contains the content for the documentation.
 

docs/conf.py

@@ -12,7 +12,6 @@
 extensions = [
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
-    "jupyter_sphinx",
     "sphinx_copybutton",
     "sphinx.ext.autosectionlabel",
     "myst_nb",

docs/index.md

@@ -0,0 +1,160 @@
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+---
+
+# Getting Started
+
+## Building a circuit with the `Circuit` class
+
+You can create a circuit by creating an instance of the `Circuit`
+class and adding gates manually.
+
+
+```{code-cell} ipython3
+
+from pytket import Circuit
+
+ghz_circ = Circuit(3)
+ghz_circ.H(0)
+ghz_circ.CX(0, 1)
+ghz_circ.CX(1, 2)
+ghz_circ.add_barrier(ghz_circ.qubits)
+ghz_circ.measure_all()
+```
+
+Now let’s draw a nice picture of the circuit with the circuit renderer
+
+
+```{code-cell} ipython3
+
+from pytket.circuit.display import render_circuit_jupyter
+
+render_circuit_jupyter(ghz_circ)
+```
+
+See also the [Circuit
+construction](https://tket.quantinuum.com/user-manual/manual_circuit.html)
+section of the user manual.
+
+## Build a `Circuit` from a QASM file
+
+Alternatively we can import a circuit from a QASM file using
+[pytket.qasm](https://tket.quantinuum.com/api-docs/qasm.html). There
+are also functions for generating a circuit from a QASM string or
+exporting to a qasm file.
+
+Note that its also possible to import a circuit from quipper using
+[pytket.quipper](https://tket.quantinuum.com/api-docs/quipper.html)
+module.
+
+
+```{code-cell} ipython3
+
+from pytket.qasm import circuit_from_qasm
+
+w_state_circ = circuit_from_qasm("examples/qasm/W-state.qasm")
+render_circuit_jupyter(w_state_circ)
+```
+
+## Import a circuit from qiskit (or other SDK)
+
+Its possible to generate a circuit directly from a qiskit
+`QuantumCircuit` using the
+[qiskit_to_tk](https://tket.quantinuum.com/extensions/pytket-qiskit/api.html#pytket.extensions.qiskit.tk_to_qiskit)
+function.
+
+
+```{code-cell} ipython3
+
+from qiskit import QuantumCircuit
+
+qiskit_circ = QuantumCircuit(3)
+qiskit_circ.h(range(3))
+qiskit_circ.ccx(2, 1 ,0)
+qiskit_circ.cx(0, 1)
+print(qiskit_circ)
+```
+
+
+```{code-cell} ipython3
+
+from pytket.extensions.qiskit import qiskit_to_tk
+
+tket_circ = qiskit_to_tk(qiskit_circ)
+
+render_circuit_jupyter(tket_circ)
+```
+
+Note that pytket and qiskit use opposite qubit ordering conventions. So
+circuits which look identical may correspond to different unitary
+operations.
+
+Circuit conversion functions are also available for
+[pytket-cirq](https://tket.quantinuum.com/extensions/pytket-cirq/),
+[pytket-pennylane](https://tket.quantinuum.com/extensions/pytket-pennylane/),
+[pytket-braket](https://tket.quantinuum.com/extensions/pytket-braket/)
+and more.
+
+## Using Backends
+
+In pytket a `Backend` represents an interface to a quantum device or
+simulator.
+
+We will show a simple example of running the `ghz_circ` defined above
+on the `AerBackend` simulator.
+
+
+```{code-cell} ipython3
+
+render_circuit_jupyter(ghz_circ)
+```
+
+
+```{code-cell} ipython3
+
+from pytket.extensions.qiskit import AerBackend
+
+backend = AerBackend()
+result = backend.run_circuit(ghz_circ)
+print(result.get_counts())
+```
+
+The `AerBackend` simulator is highly idealised having a broad gateset,
+and no restrictive connectivity or device noise.
+
+The Hadamard and CX gate are supported operations of the simulator so we
+can run the GHZ circuit without changing any of the operations. For more
+realistic cases a compiler will have to solve for the limited gateset of
+the target backend as well as other backend requirements.
+
+See the [Running on
+Backends](https://tket.quantinuum.com/user-manual/manual_backend.html)
+section of the user manual and the [backends example
+notebook](https://tket.quantinuum.com/examples/backends_example.html)
+for more.
+
+```{toctree}
+:caption: Manual
+:maxdepth: 2
+
+manual/manual_intro.rst
+manual/manual_circuit.rst
+manual/manual_backend.rst
+manual/manual_compiler.rst
+manual/manual_noise.rst
+manual/manual_assertion.rst
+manual/manual_zx.rst
+```
+
+```{toctree}
+:caption: Example Notebooks
+:glob: true
+:maxdepth: 2
+
+examples/circuit_construction/*
+examples/backends/*
+examples/circuit_compilation/*
+examples/algorithms_and_protocols/*
+```