Merge pull request #974 from haskell-servant/alp/tutorial-tweaks

website/tutorial tweaks

Author: phadej

doc/index.rst

@@ -3,22 +3,24 @@ servant – A Type-Level Web DSL
 
 .. image:: https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png
 
-**servant** is a set of packages for declaring web APIs at the type-level and
-then using those API specifications to:
+**servant** is a set of Haskell libraries for writing *type-safe* web
+applications but also *deriving* clients (in Haskell and other languages) or
+generating documentation for them, and more.
 
-- write servers (this part of **servant** can be considered a web framework),
-- obtain client functions (in haskell),
-- generate client functions for other programming languages,
-- generate documentation for your web applications
-- and more...
+This is achieved by taking as input a description of the web API
+as a Haskell type. Servant is then able to check that your server-side request
+handlers indeed implement your web API faithfully, or to automatically derive
+Haskell functions that can hit a web application that implements this API,
+generate a Swagger description or code for client functions in some other
+languages directly.
 
-All in a type-safe manner.
+If you would like to learn more, click the tutorial link below.
 
 .. toctree::
   :maxdepth: 2
 
-  introduction.rst
   tutorial/index.rst
   cookbook/index.rst
   examples.md
   links.rst
+  principles.rst

doc/introduction.rst renamed to doc/principles.rst

@@ -1,5 +1,5 @@
-Introduction
-------------
+Principles
+----------
 
 **servant** has the following guiding principles:
 

doc/tutorial/Javascript.lhs

@@ -477,7 +477,7 @@ data AngularOptions = AngularOptions
   }
 ```
 
-# Custom function name builder
+## Custom function name builder
 
 Servant comes with three name builders included:
 
@@ -518,4 +518,3 @@ var get_books = function(q, onSuccess, onError)
 }
 
 ```
-

doc/tutorial/index.rst

@@ -3,9 +3,28 @@ Tutorial
 
 This is an introductory tutorial to **servant**. Whilst browsing is fine, it makes more sense if you read the sections in order, or at least read the first section before anything else.
 
-(Any comments, issues or feedback about the tutorial can be submitted
-to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.)
+Any comments, issues or feedback about the tutorial can be submitted
+to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.
 
+In fact, the whole tutorial is a `cabal <https://cabal.readthedocs.io/en/latest/>`_
+project and can be built and played with locally as follows:
+
+.. code-block:: bash
+
+   $ git clone https://github.com/haskell-servant/servant.git
+   $ cd servant
+   # build
+   $ cabal new-build tutorial
+   # load in ghci to play with it
+   $ cabal new-repl tutorial
+
+The code can be found in the `*.lhs` files under `doc/tutorial/` in the
+repository. Feel free to edit it while you're reading this documentation and
+see the effect of your changes.
+
+`Nix <https://nixos.org/nix/>`_ users should feel free to take a look at
+the `nix/shell.nix` file in the repository and use it to provision a suitable
+environment to build and run the examples.
 
 .. toctree::
   :maxdepth: 1