added (final) v4 repo docs

- added very cute, very essential emojis to markdown titles
- added a tutorial
- added a main docs/README.md
- added a main tests/README.md
- made markdown hyperlinks work on both Github and Doxygen
- made markdown files appear as Doxygen pages
- made macros appear in Doxygen docs via function/const/typedef spoofing
- patched code snippet syntax (from C++ to cpp; doxygen didn't recognise the former)
- renamed run.md to launch.md

See the commit breakdown in PR #585

The macro spoofing was necessary to workaround the Doxygen limitation described here:
https://stackoverflow.com/questions/79548865

Note that hyperlinks to sections within the markdown files (e.g. `[x](file.md#section)`) cannot be handled by Doxygen at all. A user clicking such a hyperlink in the generated html will hit a 404. These little user-traps have been marked with comments in the markdown files. Alas!

Author: TysonRayJones

README.md

@@ -40,7 +40,7 @@
 <!-- intro -->
 
 > [!NOTE]
-> QuEST `v4` has been released which re-designed QuEST from the ground up. Read about the exciting new features [here](/docs/v4.md).
+> QuEST `v4` has been released which re-designed QuEST from the ground up. Read about the exciting new features [here](docs/v4.md).
 
 The **Quantum Exact Simulation Toolkit** (QuEST) is a high-performance simulator of quantum statevectors and density matrices.
 It hybridises **multithreading**, **GPU acceleration** and **distribution** to run lightning fast on laptops, desktops and 
@@ -83,19 +83,16 @@ In particular, QuEST `v4` was made possible through the support of the UK Nation
 
 </div>
 
-To learn more:
 
+<!-- <a> used below for doxygen compatibility -->
+
+To learn more:
+- view the <a href="#main_documentation">documentation</a>
 - visit the [website](https://quest.qtechtheory.org/)
-- see some [examples](/examples/)
-- view the [documentation](#documentation)
-- browse the [API](https://quest-kit.github.io/QuEST/group__api.html)
 - read the [whitepaper](https://www.nature.com/articles/s41598-019-47174-9), which featured in Scientific Report's [Top 100 in Physics](https://www.nature.com/collections/ecehgdfcba/) :trophy:
 
-<div align="center">
 
 
-</div>
-
 ---------------------------------
 
 
@@ -105,7 +102,7 @@ To learn more:
 ## 🎉  Introduction
 
 QuEST has a simple interface which is agnostic to whether it's running on CPUs, GPUs or a networked supercomputer.
-```C++
+```cpp
 Qureg qureg = createQureg(30);
 initRandomPureState(qureg);
 
@@ -119,7 +116,7 @@ qreal prob  = calcProbOfQubitOutcome(qureg, 0, outcome);
 qreal expec = calcExpecPauliStr(qureg, getPauliStr("XYZ"));
 ```
 Yet, it is flexible
-```C++
+```cpp
 mixDepolarising(qureg, targ, prob);
 mixKrausMap(qureg, targs, ntargs, krausmap);
 
@@ -133,7 +130,7 @@ multiplyCompMatr1(qureg, targ, getInlineCompMatr1( {{1,2i},{3i,4}} ));
 multiplyDiagMatrPower(qureg, targs, ntargs, diagmatr, exponent);
 ```
 and extremely powerful
-```C++
+```cpp
 setFullStateDiagMatrFromMultiVarFunc(fullmatr, myfunc, ntargsPerVar, nvars);
 applyFullStateDiagMatrPower(qureg, fullmatr, exponent);
 
@@ -181,19 +178,15 @@ QuEST supports:
 
 ---------------------------------
 
+<!-- permit doxygen to reference section -->
+<a id="main_documentation"></a>
+
 ## 📖  Documentation
 
 > [!IMPORTANT]
 > QuEST v4's documentation is still under construction!
 
-Visit the [docs](docs/) to:
-  - [see what's new in v4](docs/v4.md)
-  - [compile with cmake](docs/compile.md)
-  - [find compatible compilers](docs/compilers.md)
-  - [launch your simulations](docs/run.md)
-  - [view some examples](examples/)
-
-The [API](https://quest-kit.github.io/QuEST/group__api.html) documentation is divided into the following groups:
+Visit the [docs](docs/README.md) for guides and tutorials, or the [API](https://quest-kit.github.io/QuEST/group__api.html) which is divided into:
   - [calculations](https://quest-kit.github.io/QuEST/group__calculations.html)
   - [channels](https://quest-kit.github.io/QuEST/group__channels.html)
   - [debug](https://quest-kit.github.io/QuEST/group__debug.html)
@@ -241,10 +234,6 @@ You can also browse QuEST's extensive [tests](https://quest-kit.github.io/QuEST/
   - [deprecated test utilities](https://quest-kit.github.io/QuEST/group__deprecatedutils.html)
 -->
 
-Contributers to QuEST should also check out the:
-  - [software architecture](docs/architecture.md)
-  - [style guide](docs/styleguide.md)
-
 ---------------------------------
 
 ## 🚀  Getting started 
@@ -270,7 +259,7 @@ then run it with
 ./min_example
 ```
 
-See the [docs](docs/) for enabling acceleration and running the unit tests.
+See the [docs](docs/README.md) for enabling acceleration and running the unit tests.
 
 ---------------------------------
 

docs/README.md

@@ -1,17 +1,53 @@
-> TODO
+# 📖  Documentation
 
-> not sure where to put below (snippet from DiRAC)
+<!--
+  Doc overview
+  (this comment must be under the title for valid doxygen rendering)
 
-gpu_launch.sh wrapper script
-The gpu_launch.sh wrapper script is required to set the correct binding of GPU to MPI processes and the correct binding of interconnect interfaces to MPI process and GPU. We provide this centrally for convenience but its contents are simple:
+  @author Tyson Jones
+-->
 
-```
-#!/bin/bash
+<!-- @todo remove this when doc done -->
+> [!IMPORTANT]  
+> QuEST's `v4` documentation is still under construction.
+
+QuEST has been overhauled! See
+
+- 🎉  [`v4.md`](v4.md) for the exciting new features.
+
+To get started with QuEST, check out
+
+- 🔧  [`compilers.md`](compilers.md) for a list of compatible compilers.
+- 🔗  [`qtechtheory.org`](https://quest.qtechtheory.org/download/) for some help downloading compilers.
+- 🛠️  [`compile.md`](compile.md) for instructions on compiling.
+- ⚙️  [`cmake.md`](cmake.md) for a list of compiler variables.
+- 🚀  [`launch.md`](launch.md) to learn how to run QuEST on laptops to supercomputers.
+- 🎓  [`tutorial.md`](tutorial.md) for an introductory tutorial.
+- 📋  [API](https://quest-kit.github.io/QuEST/group__api.html) for the documentation of each function.
 
-# Compute the raw process ID for binding to GPU and NIC
-lrank=$((SLURM_PROCID % SLURM_NTASKS_PER_NODE))
+Interested in contributing? Then check out:
 
-# Bind the process to the correct GPU and NIC
-export CUDA_VISIBLE_DEVICES=${lrank}
-export UCX_NET_DEVICES=mlx5_${lrank}:1
+- ❤️  [`contributing.md`](contributing.md) to learn how to make a pull request.
+- 🏗️  [`architecture.md`](architecture.md) to understand the code structure.
+- 🎨  [`styleguide.md`](styleguide.md) for some tips on writing neat code.
+
+Want to learn how what's under the hood? Read the
+- 🏆  [whitepaper](https://www.nature.com/articles/s41598-019-47174-9) which featured in Scientific Report's [Top 100 in Physics](https://www.nature.com/collections/ecehgdfcba/)
+- 📝  [preprint](https://arxiv.org/abs/2311.01512) which derives `v4`'s optimised algorithms.
+- 🧪  [tests](/tests) which compare QuEST's outputs to non-optimised calculations.
+- 📈  [benchmarks](https://www.youtube.com/watch?v=dQw4w9WgXcQ) which are coming soon!
+
+
+If QuEST is useful to you, feel free to cite
+```
+@article{jones2019quest,
+  title={QuEST and high performance simulation of quantum computers},
+  author={Jones, Tyson and Brown, Anna and Bush, Ian and Benjamin, Simon C},
+  journal={Scientific reports},
+  volume={9},
+  number={1},
+  pages={10736},
+  year={2019},
+  publisher={Nature Publishing Group UK London}
+}
 ```

docs/architecture.md

@@ -1,11 +1,12 @@
+# 🏗️  Architecture
+
 <!--
   Explanation of QuEST's software architecture
+  (this comment must be under the title for valid doxygen rendering)
   
   @author Tyson Jones
 -->
 
-# Architecture
-
 All user-visible API signatures are contained in `include/`, divided into semantic submodules (like `calculations.h` and `qureg.h`), but all exposed by `quest.h`. They are all strictly `C` _and_ `C++` compatible, hence their `.h` file extension.
 
 The source code within `src/` is divided between five subdirectories, listed below in order of increasing control flow depth. All code is parsed strictly by `C++`, hence all files have `.cpp` and `.hpp` extensions.

docs/cmake.md

@@ -1,13 +1,13 @@
+# ⚙️  CMake
+
 <!--
   Instructions for compiling QuEST with CMake
+  (this comment must be under the title for valid doxygen rendering)
 
   @author Oliver Thomson Brown
   @author Tyson Jones (test variables)
 -->
 
-
-# CMake Configuration Options in QuEST
-
 Version 4 of QuEST includes reworked CMake to support library builds, CMake export, and installation. Here we detail useful variables to configure the compilation of QuEST. If using a Unix-like operating system any of these variables can be set using the `-D` flag when invoking CMake, for example:
 
 ```