From 11928bcdd2cf00f6d2beccf049e27481c1bb5e88 Mon Sep 17 00:00:00 2001 From: Alp Mestanogullari Date: Sun, 10 Jun 2018 00:43:02 +0200 Subject: [PATCH] website/tutorial tweaks --- doc/index.rst | 20 +++++++++++--------- doc/{introduction.rst => principles.rst} | 4 ++-- doc/tutorial/Javascript.lhs | 3 +-- doc/tutorial/index.rst | 23 +++++++++++++++++++++-- 4 files changed, 35 insertions(+), 15 deletions(-) rename doc/{introduction.rst => principles.rst} (98%) diff --git a/doc/index.rst b/doc/index.rst index 05f2b6ff..a31f34fd 100644 --- a/doc/index.rst +++ b/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 diff --git a/doc/introduction.rst b/doc/principles.rst similarity index 98% rename from doc/introduction.rst rename to doc/principles.rst index 4340fe34..9eee9628 100644 --- a/doc/introduction.rst +++ b/doc/principles.rst @@ -1,5 +1,5 @@ -Introduction ------------- +Principles +---------- **servant** has the following guiding principles: diff --git a/doc/tutorial/Javascript.lhs b/doc/tutorial/Javascript.lhs index 033735ed..fbcd3c95 100644 --- a/doc/tutorial/Javascript.lhs +++ b/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) } ``` - diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index ff55a240..c72b154d 100644 --- a/doc/tutorial/index.rst +++ b/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 `_.) +Any comments, issues or feedback about the tutorial can be submitted +to `servant's issue tracker `_. +In fact, the whole tutorial is a `cabal `_ +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 `_ 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