doc: improve readme

1 files changed, 53 insertions, 1 deletions

diff --git a/README.rst b/README.rst
index b01ee4e..daac1eb 100644
--- a/README.rst
+++ b/README.rst
@@ -9,7 +9,59 @@ The `newtype` library provides types and functions to facilitate the creation of
 Usage
 =====
 
-Please `Read the Docs <https://newtype.rtfd.io>`_ for an introduction to the library.
+The code block below demonstrates the basic usage and features of `newtype`. For a more details description of the library, as well as a full API documentation, please `read the docs <https://newtype.rtfd.io>`_ (also available as a `PDF file <https://readthedocs.org/projects/newtype/downloads/pdf/latest/>`_).
+
+.. code-block:: c++
+   
+   #include <newtype/derivable.hpp>
+   #include <newtype/deriving.hpp>
+   #include <newtype/new_type.hpp>
+   
+   #include <iostream>
+   
+   using Width = nt::new_type<unsigned int, struct width_tag, deriving(nt::Read)>;
+   using Height = nt::new_type<unsigned int, struct height_tag, deriving(nt::Read)>;
+   using Area = nt::new_type<unsigned int, struct area_tag, deriving(nt::Show)>;
+   
+   struct Rectangle
+   {
+     constexpr Rectangle(Width w, Height h)
+         : width{w}
+         , height{h}
+     {
+     }
+   
+     auto constexpr area() const noexcept -> Area
+     {
+       return {width.decay() * height.decay()};
+     }
+   
+   private:
+     Width width;
+     Height height;
+   };
+   
+   int main()
+   {
+     auto width = Width{};
+     auto height = Height{};
+   
+     std::cin >> width >> height;
+   
+     auto rect = Rectangle{width, height};
+   
+     std::cout << rect.area() << '\n';
+   }
+
+Requirements
+============
+
+This library uses features of C++20 and thus requires a modern compiler.
+All development was done on GCC 9.2.
+This is a header-only library, and thus no compilation is need if you want to use it in your project.
+If you want to run the sanity-checks/unit-test, you will need at least CMake 3.9.0.
+If you want to build to documentation, you will need either a local installation of sphinx, or alternatively `pipenv`.
+A `Pipfile` is provided in the directory `docs` within the source root.
 
 .. |c++20| image:: https://img.shields.io/badge/c%2B%2B-20-orange
    :alt: C++20