doc: Update readme

README.md

@@ -1,29 +1,68 @@
 # Guppy
 
-## About
+Guppy is a quantum programming language that is fully embedded into Python.
+It allows you to write high-level hybrid quantum programs with classical control flow and mid-circuit measurements using Pythonic syntax:
+
+```python
+from guppylang import guppy, Qubit
+
+@guppy
+def teleport(src: Qubit, tgt: Qubit) -> Qubit:
+   """Teleports the state in `src` to `tgt`."""
+   # Create ancilla and entangle it with src and tgt
+   tmp = Qubit()
+   tmp, tgt = cx(h(tmp), tgt)
+   src, tmp = cx(src, tmp)
+
+   # Apply classical corrections
+   if measure(h(src)):
+      tgt = z(tgt)
+   if measure(tmp):
+      tgt = x(tgt)
+   return tgt
+```
+
+More examples and tutorials are available [here][examples].
+
+[examples]: ./examples/
+
 
-TODO
+## Install
+
+Guppy can be installed via `pip`. Requires Python >= 3.10.
+
+```sh
+pip install guppylang
+```
 
-## Getting Started
+
+## Usage
+
+See the [Getting Started][getting-started] guide and the other [examples].
+
+[getting-started]: ./examples/1-Getting-Started.md
+
+
+## Development
 
 These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.
 
 ### Prerequisites
 
-- Python >=3.10
+- Python >= 3.10
+- [Poetry](https://python-poetry.org/docs/#installation)
+- [Rust](https://www.rust-lang.org/tools/install) >= 1.75.0  (only needed for tests)
 
 ### Installing
 
-
-First make sure poetry [is
-installed](https://python-poetry.org/docs/#installation).
-
-Then run the following to setup your virtual environment and install dependencies:
+Run the following to setup your virtual environment and install dependencies:
 
 ```sh
-poetry install
+poetry install --with validation
 ```
 
+Note that the `--with validation` flag is optional and only needed to run integration tests.
+
 You can then activate the virtual environment and work within it with:
 
 ```sh
@@ -35,50 +74,42 @@ automate this when entering and leaving a directory.
 
 To run a single command in the shell, just prefix it with `poetry run`.
 
+### Pre-commit
 
-### Git blame
-
-You can configure Git to ignore formatting commits when using `git blame` by running
+Install the pre-commit hook by running:
 
 ```sh
-git config blame.ignoreRevsFile .git-blame-ignore-revs
+poetry run pre-commit install
 ```
 
-## Usage
 
-TODO
+### Testing
 
-## Testing
-
-First, build the PyO3 Hugr validation library from the `validator` directory using
+Run tests using
 
 ```sh
-maturin develop
+poetry run pytest -v
 ```
 
-Run tests using
+You have to install extra dependencies to test automatic circuit conversion from `pytket`:
 
 ```sh
-poetry run pytest -v
+poetry install --extras=pytket
+poetry run pytest -v  # Now rerun tests
 ```
 
+
 Integration test cases can be exported to a directory using
 
 ```sh
 poetry run pytest --export-test-cases=guppy-exports
-
 ```
 
 which will create a directory `./guppy-exports` populated with hugr modules serialised in msgpack.
 
-## Packaging
-
-```sh
-poetry build
-```
 
 ## License
 
-This project is licensed under Apache License, Version 2.0 ([LICENSE][] or http://www.apache.org/licenses/LICENSE-2.0).
+This project is licensed under Apache License, Version 2.0 ([LICENCE][] or http://www.apache.org/licenses/LICENSE-2.0).
 
-  [LICENSE]: ./LICENSE
+  [LICENCE]: ./LICENCE

examples/1-Getting-Started.md

@@ -0,0 +1,7 @@
+
+# 1. Getting Started
+
+This file explains how you can get started using Guppy.
+
+TODO
+