git.iko.soy/servant
on master help sign in
tutorial: restructuring
9263f97Sönke Hahn
doc/CONTRIBUTING.mddeleted−1
compare with master
unifiedsplit
@@ -1 +0,0 @@
1−../CONTRIBUTING.md
doc/README.mddeleted−1
@@ -1 +0,0 @@
1−../README.md
doc/index.rst+8−6
@@ -1,12 +1,14 @@
1−servant – Type-Level Web DSL
1+servant – A Type-Level Web DSL
2−============================
2+==============================
3+
4+.. image:: https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png
3
5
4Documentation table of contents
6Documentation table of contents
5-------------------------------
7-------------------------------
6
8
7.. toctree::
9.. toctree::
8− :maxdepth: 2
10+ :maxdepth: 2
9
11
10− README.md
12+ introduction.rst
11− tutorial/index.rst
13+ tutorial/index.rst
12− CONTRIBUTING.md
14+ links.rst
doc/introduction.rstnew file+44
@@ -0,0 +1,44 @@
1+Introduction
2+------------
3+
4+*servant* has the following guiding principles:
5+
6+- concision
7+
8+ This is a pretty wide-ranging principle. You should be able to get nice
9+ documentation for your web servers, and client libraries, without repeating
10+ yourself. You should not have to manually serialize and deserialize your
11+ resources, but only declare how to do those things *once per type*. If a
12+ bunch of your handlers take the same query parameters, you shouldn't have to
13+ repeat that logic for each handler, but instead just "apply" it to all of
14+ them at once. Your handlers shouldn't be where composition goes to die. And
15+ so on.
16+
17+- flexibility
18+
19+ If we haven't thought of your use case, it should still be easily
20+ achievable. If you want to use templating library X, go ahead. Forms? Do
21+ them however you want, but without difficulty. We're not opinionated.
22+
23+- separation of concerns
24+
25+ Your handlers and your HTTP logic should be separate. True to the philosphy
26+ at the core of HTTP and REST, with *servant* your handlers return normal
27+ Haskell datatypes - that's the resource. And then from a description of your
28+ API, *servant* handles the *presentation* (i.e., the Content-Types). But
29+ that's just one example.
30+
31+- type safety
32+
33+ Want to be sure your API meets a specification? Your compiler can check
34+ that for you. Links you can be sure exist? You got it.
35+
36+To stick true to these principles, we do things a little differently than you
37+might expect. The core idea is *reifying the description of your API*. Once
38+reified, everything follows. We think we might be the first web framework to
39+reify API descriptions in an extensible way. We're pretty sure we're the first
40+to reify it as *types*.
41+
42+To be able to write a webservice you only need to read the first two sections,
43+but the goal of this document being to get you started with servant, we also
44+cover the couple of ways you can extend servant for a great good.
doc/links.rstnew file+34
@@ -0,0 +1,34 @@
1+
2+Helpful Links
3+-------------
4+
5+- the central documentation (this site):
6+ `haskell-servant.readthedocs.org <http://haskell-servant.readthedocs.org/>`_
7+
8+- the github repo:
9+ `github.com/haskell-servant/servant <https://github.com/haskell-servant/servant>`_
10+
11+- the issue tracker (Feel free to create issues and submit PRs!):
12+ `https://github.com/haskell-servant/servant/issues <https://github.com/haskell-servant/servant/issues>`_
13+
14+- the irc channel:
15+ #servant on freenode
16+
17+- the mailing list:
18+ `groups.google.com/forum/#!forum/haskell-servant <https://groups.google.com/forum/#!forum/haskell-servant>`_
19+
20+- blog posts and videos and slides of some talks on servant:
21+ `haskell-servant.github.io <http://haskell-servant.github.io>`_
22+
23+- the servant packages on hackage:
24+
25+ - `hackage.haskell.org/package/servant <http://hackage.haskell.org/package/servant>`_
26+ - `hackage.haskell.org/package/servant-server <http://hackage.haskell.org/package/servant-server>`_
27+ - `hackage.haskell.org/package/servant-client <http://hackage.haskell.org/package/servant-client>`_
28+ - `hackage.haskell.org/package/servant-blaze <http://hackage.haskell.org/package/servant-blaze>`_
29+ - `hackage.haskell.org/package/servant-lucid <http://hackage.haskell.org/package/servant-lucid>`_
30+ - `hackage.haskell.org/package/servant-cassava <http://hackage.haskell.org/package/servant-cassava>`_
31+ - `hackage.haskell.org/package/servant-docs <http://hackage.haskell.org/package/servant-docs>`_
32+ - `hackage.haskell.org/package/servant-foreign <http://hackage.haskell.org/package/servant-foreign>`_
33+ - `hackage.haskell.org/package/servant-js <http://hackage.haskell.org/package/servant-js>`_
34+ - `hackage.haskell.org/package/servant-mock <http://hackage.haskell.org/package/servant-mock>`_
doc/tutorial/index.rst+2−56
@@ -1,64 +1,10 @@
1−Servant tutorial
1+Tutorial
2−================
2+========
3
3
4This is an introductory tutorial to the current version of *servant*, which is
4This is an introductory tutorial to the current version of *servant*, which is
5**0.4**. Any comment or issue can be directed to `this website's issue
5**0.4**. Any comment or issue can be directed to `this website's issue
6tracker <http://github.com/haskell-servant/haskell-servant.github.io/issues>`_.
6tracker <http://github.com/haskell-servant/haskell-servant.github.io/issues>`_.
7
7
8−Github
9−-------
10−
11−- the servant packages: `haskell-servant/servant <https://github.com/haskell-servant/servant>`_
12−- the website (including this tutorial): `haskell-servant/haskell-servant.github.io <https://github.com/haskell-servant/haskell-servant.github.io/>`_
13−- Feel free to use the issue tracker (or to send PRs!) on the website's repository to give feedback and suggestions about this tutorial
14−
15−Introduction
16−-------------
17−
18−*servant* has the following guiding principles:
19−
20−- concision
21−
22− This is a pretty wide-ranging principle. You should be able to get nice
23− documentation for your web servers, and client libraries, without repeating
24− yourself. You should not have to manually serialize and deserialize your
25− resources, but only declare how to do those things *once per type*. If a
26− bunch of your handlers take the same query parameters, you shouldn't have to
27− repeat that logic for each handler, but instead just "apply" it to all of
28− them at once. Your handlers shouldn't be where composition goes to die. And
29− so on.
30−
31−- flexibility
32−
33− If we haven't thought of your use case, it should still be easily
34− achievable. If you want to use templating library X, go ahead. Forms? Do
35− them however you want, but without difficulty. We're not opinionated.
36−
37−- separation of concerns
38−
39− Your handlers and your HTTP logic should be separate. True to the philosphy
40− at the core of HTTP and REST, with *servant* your handlers return normal
41− Haskell datatypes - that's the resource. And then from a description of your
42− API, *servant* handles the *presentation* (i.e., the Content-Types). But
43− that's just one example.
44−
45−- type safety
46−
47− Want to be sure your API meets a specification? Your compiler can check
48− that for you. Links you can be sure exist? You got it.
49−
50−To stick true to these principles, we do things a little differently than you
51−might expect. The core idea is *reifying the description of your API*. Once
52−reified, everything follows. We think we might be the first web framework to
53−reify API descriptions in an extensible way. We're pretty sure we're the first
54−to reify it as *types*.
55−
56−To be able to write a webservice you only need to read the first two sections,
57−but the goal of this document being to get you started with servant, we also
58−cover the couple of ways you can extend servant for a great good.
59−
60−Tutorial
61−---------
62
8
63.. toctree::
9.. toctree::
64 :maxdepth: 1
10 :maxdepth: 1