From 7fa7e8302fd944c01ac4f2643cac65c3077296f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lucas=20Fr=C3=A9rot?= <lucas.frerot@imtek.uni-freiburg.de>
Date: Thu, 22 Dec 2022 10:03:09 +0100
Subject: [PATCH] updated README

---
 README.rst | 77 ++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 52 insertions(+), 25 deletions(-)

diff --git a/README.rst b/README.rst
index c5df9274..c604136b 100644
--- a/README.rst
+++ b/README.rst
@@ -1,58 +1,85 @@
 Matscipy
 ========
 
-This repository contains generic Python materials science tools built
-around the `Atomic Simulation Environment
-(ASE) <https://wiki.fysik.dtu.dk/ase/>`__.
+Matscipy is a generic materials science toolbox built around the `Atomic
+Simulation Environment (ASE) <https://wiki.fysik.dtu.dk/ase/>`__. It provides
+useful routines for:
 
-Build status
-------------
-
-|Build Status|
+- Plasticity and dislocations
+- Fracture mechanics
+- Electro-chemistry
+- Tribology
+- Elastic properties
 
-Compilation/installation follows the standard distutils route:
+In addition to domain-specific routines, it also implements a set of
+general-purpose, low-level utilies:
 
-::
+- Efficient neighbour lists
+- Atomic strain
+- Ring analysis
+- Correlation functions
+- Second order potential derivatives
 
-   python setup.py build
-   python setup.py install
+Quick start
+-----------
 
-If building on Mac OS X, we recommend you use the GCC toolchain
+Matscipy can be installed on Windows, Linux and x86 macos with::
 
-::
+  python3 -m pip install matscipy
 
-   CC=gcc CXX=g++ python setup.py build
-   
-If you have a recent version of gcc you may also need to set
+To get the latest version directly (requires a working compiler)::
 
-::
+  python3 -m pip install git+https://github.com/libAtoms/matscipy.git
 
-    CFLAGS="-std=c99"
+Compiled up-to-date wheels for Windows, Linux and x86 macos can be found `here
+<https://github.com/libAtoms/matscipy/actions/workflows/build-wheels.yml>`__.
 
 Documentation
 -------------
 
-`Sphinx <http://sphinx-doc.org/>`__-generated documentation for the
-project can be found `here <http://libatoms.github.io/matscipy/>`__.
+`Sphinx <http://sphinx-doc.org/>`__-generated documentation for the project can
+be found `here <http://libatoms.github.io/matscipy/>`__. Since Matscipy is built
+on top of ASE's `Atoms
+<https://wiki.fysik.dtu.dk/ase/ase/atoms.html#module-ase.atoms>`__ and
+`Calculator <https://wiki.fysik.dtu.dk/ase/ase/calculators/calculators.html>`__
+objects, ASE's documentation is a good complement to Matscipy's.
+
+Seeking help
+------------
+
+`Issues <https://github.com/libAtoms/matscipy/issues>`__ can be used to ask
+questions about Matscipy.
+
+Contributing
+------------
+
+Contributions, in the form of bug reports, improvement suggestions,
+documentation or pull requests, are welcome.
+
+Running tests
+~~~~~~~~~~~~~
+
+To run the tests locally, from Matscipy's root directory::
+
+  python3 -m pip install .[test]  # installs matscipy + test dependencies
+  cd tests/
+  python3 -m pytest .
 
 Dependencies
 ------------
 
-The package requires :
+The package requires:
 
 -  **numpy** - http://www.numpy.org/
 -  **scipy** - http://www.scipy.org/
 -  **ASE** - https://wiki.fysik.dtu.dk/ase/
 
-Optional packages :
+Optional packages:
 
 -  **quippy** - http://www.github.com/libAtoms/QUIP
 -  **atomistica** - https://www.github.com/Atomistica/atomistica
 -  **chemview** - https://github.com/gabrielelanaro/chemview
 
-.. |Build Status| image:: https://travis-ci.org/libAtoms/matscipy.svg?branch=master
-   :target: https://travis-ci.org/libAtoms/matscipy
-
 Funding
 -------