git.iko.soy/typeable/servant
on master help sign in
Merge pull request #974 from haskell-servant/alp/tutorial-tweaks

website/tutorial tweaks

commit2edaa5d95b8fe22d47710991ea7d08612a811867 authorOleg Grenrus <oleg.grenrus@iki.fi> dateWed 13 Jun 2018, 01:25 (8 years ago) parent507263e11928bc
4 files changed+35−15
compare with master
unifiedsplit
doc/index.rst+11−9 doc/introduction.rst → doc/principles.rst+2−2 doc/tutorial/Javascript.lhs+1−2 doc/tutorial/index.rst+21−2
doc/index.rst+11−9
@@ -3,22 +3,24 @@ servant – A Type-Level Web DSL
33
44.. image:: https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png
55
6−**servant** is a set of packages for declaring web APIs at the type-level and
7−then using those API specifications to:
6+**servant** is a set of Haskell libraries for writing *type-safe* web
7+applications but also *deriving* clients (in Haskell and other languages) or
8+generating documentation for them, and more.
89
9−- write servers (this part of **servant** can be considered a web framework),
10−- obtain client functions (in haskell),
11−- generate client functions for other programming languages,
12−- generate documentation for your web applications
13−- and more...
10+This is achieved by taking as input a description of the web API
11+as a Haskell type. Servant is then able to check that your server-side request
12+handlers indeed implement your web API faithfully, or to automatically derive
13+Haskell functions that can hit a web application that implements this API,
14+generate a Swagger description or code for client functions in some other
15+languages directly.
1416
15−All in a type-safe manner.
17+If you would like to learn more, click the tutorial link below.
1618
1719.. toctree::
1820 :maxdepth: 2
1921
20− introduction.rst
2122 tutorial/index.rst
2223 cookbook/index.rst
2324 examples.md
2425 links.rst
26+ principles.rst
doc/introduction.rst → doc/principles.rstrenamed+2−2
@@ -1,5 +1,5 @@
1−Introduction
2−------------
1+Principles
2+----------
33
44**servant** has the following guiding principles:
55
doc/tutorial/Javascript.lhs+1−2
@@ -477,7 +477,7 @@ data AngularOptions = AngularOptions
477477 }
478478```
479479
480−# Custom function name builder
480+## Custom function name builder
481481
482482Servant comes with three name builders included:
483483
@@ -518,4 +518,3 @@ var get_books = function(q, onSuccess, onError)
518518}
519519
520520```
521−
doc/tutorial/index.rst+21−2
@@ -3,9 +3,28 @@ Tutorial
33
44This 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.
55
6−(Any comments, issues or feedback about the tutorial can be submitted
7−to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.)
6+Any comments, issues or feedback about the tutorial can be submitted
7+to `servant's issue tracker <http://github.com/haskell-servant/servant/issues>`_.
88
9+In fact, the whole tutorial is a `cabal <https://cabal.readthedocs.io/en/latest/>`_
10+project and can be built and played with locally as follows:
11+
12+.. code-block:: bash
13+
14+ $ git clone https://github.com/haskell-servant/servant.git
15+ $ cd servant
16+ # build
17+ $ cabal new-build tutorial
18+ # load in ghci to play with it
19+ $ cabal new-repl tutorial
20+
21+The code can be found in the `*.lhs` files under `doc/tutorial/` in the
22+repository. Feel free to edit it while you're reading this documentation and
23+see the effect of your changes.
24+
25+`Nix <https://nixos.org/nix/>`_ users should feel free to take a look at
26+the `nix/shell.nix` file in the repository and use it to provision a suitable
27+environment to build and run the examples.
928
1029.. toctree::
1130 :maxdepth: 1