docs: port manual source material to MyST markdown

[CalMacCQ]

Description

Porting the manual source to MyST to allow easier use of the MyST library. We now use the MyST-nb library for building both the manual and examples pages. This ensures visual consistency of the example snippets.

Read the docs on markdown only notebooks -> https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html

Instructions for building the html locally -> https://github.com/CQCL/pytket-docs/tree/main/docs#building-the-docs (let me know if these are unclear)

I'd also recommend using the MyST VSCode extension in review -> https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight

Preview

Most of the conversion can be done in an automated way using rst-to-myst

rst2myst convert docs/manual/*.rst

This works for just about everything apart from .. jupyter-execute:: directives which I rsubstitue with equivalent `

{code-cell} ipython3

sytax with VSCode find and replace.

Example replacement for jupyter-execute directives

```{code-cell} ipython3

from pytket import Circuit
from pytket.extensions.qiskit import AerBackend
from pytket.utils import probs_from_counts

circ = Circuit(2, 2)
circ.H(0).X(1).measure_all()
backend = AerBackend()
compiled_circ = backend.get_compiled_circuit(circ)

handle = backend.process_circuit(compiled_circ, n_shots=2000)
counts = backend.get_result(handle).get_counts()
print(counts)

print(probs_from_counts(counts))

Example replacement for jupyter-input/output directives

Input (truncated)

```{code-cell} ipython3
---
tags: [skip-execution]
---

from pytket import Circuit
from pytket.extensions.qiskit import IBMQBackend
from pytket.utils import expectation_from_counts

backend = IBMQBackend("ibmq_quito")

state = Circuit(3)
state.H(0).CX(0, 1).CX(1, 2).X(0)

Output

(1.2047999999999999-0.0015000000000000013j)

Example of a cell which raises an error

```{code-cell} ipython3
---
tags: [raises-exception]
---

from pytket import Circuit, Qubit, Bit

circ = Circuit()
# set up a circuit with qubit a[0]
circ.add_qubit(Qubit("a", 0))

# rejected because "a" is already a qubit register
circ.add_bit(Bit("a", 1))

Related issues

closes #366

[willsimmons1465]

Remove the extra line and tabs

[CalMacCQ]

Thanks for spotting these formatting issues.

I fixed them in ad08277

[willsimmons1465]

Nicely done! Some of the code cells are inconsistently formatted with whitespace, so the only changes needed are going through to fix that.

I'm presuming from the existing content using MyST that it fully works with CI, i.e. if a cell fails to run CI would report an error?

[CalMacCQ]

Nicely done! Some of the code cells are inconsistently formatted with whitespace, so the only changes needed are going through to fix that.

Appreciate the review! I'll fix the formatting issues shortly.

I'm presuming from the existing content using MyST that it fully works with CI, i.e. if a cell fails to run CI would report an error?

Yes indeed. The sphinx build should error if the code cell raises and error and cause a C.I. failure.

The C.I. has some issues at the moment which should be fixed by #372 . After that is merged I can deliberately make a cell fail as a test to see if its picked up in C.I.

[CalMacCQ]

Added some code which errored out in 0bb46c3 and this caused C.I. to fail with a CellExecutionError which is reassuring.

[willsimmons1465]

I missed this one in the last review, sorry

[CalMacCQ]

Thanks Will, fixed in 4b7448b

[CalMacCQ]

I did a search to try and rule out other indentation issues, didn't find any but maybe the search pattern could be wrong.

[willsimmons1465]

Looks good to go! Thanks for sorting this out