From f12c88b45128fff0938c2cc5716c69e40b60b628 Mon Sep 17 00:00:00 2001
From: Mark Koch <mark.koch@quantinuum.com>
Date: Fri, 19 Jan 2024 14:01:59 +0000
Subject: [PATCH] doc: Update readme

---
 README.md                     | 75 +++++++++++++++++++++++++----------
 examples/1-Getting-Started.md |  7 ++++
 2 files changed, 61 insertions(+), 21 deletions(-)
 create mode 100644 examples/1-Getting-Started.md

diff --git a/README.md b/README.md
index 7f57ee83..8ccb201e 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,61 @@
 # 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
+
+@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/
+
+
+## Install
+
+Guppy can be installed via `pip`. Requires Python >= 3.10.
 
-TODO
+```sh
+pip install guppylang
+```
+
+
+## Usage
 
-## Getting Started
+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
 
 ### 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
@@ -35,20 +72,16 @@ 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
 
@@ -66,19 +99,19 @@ 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
+### 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
diff --git a/examples/1-Getting-Started.md b/examples/1-Getting-Started.md
new file mode 100644
index 00000000..047f1a56
--- /dev/null
+++ b/examples/1-Getting-Started.md
@@ -0,0 +1,7 @@
+
+# 1. Getting Started
+
+This file explains how you can get started using Guppy.
+
+TODO
+