tutorial: restructuring

doc/CONTRIBUTING.md

@@ -1 +0,0 @@
-../CONTRIBUTING.md

doc/README.md

@@ -1 +0,0 @@
-../README.md

doc/index.rst

@@ -1,12 +1,14 @@
-servant – Type-Level Web DSL
-============================
+servant – A Type-Level Web DSL
+==============================
+
+.. image:: https://raw.githubusercontent.com/haskell-servant/servant/master/servant.png
 
 Documentation table of contents
 -------------------------------
 
 .. toctree::
-   :maxdepth: 2
+  :maxdepth: 2
 
-   README.md
-   tutorial/index.rst
-   CONTRIBUTING.md
+  introduction.rst
+  tutorial/index.rst
+  links.rst

doc/introduction.rst

@@ -0,0 +1,44 @@
+Introduction
+------------
+
+*servant* has the following guiding principles:
+
+- concision
+
+   This is a pretty wide-ranging principle. You should be able to get nice
+   documentation for your web servers, and client libraries, without repeating
+   yourself. You should not have to manually serialize and deserialize your
+   resources, but only declare how to do those things *once per type*. If a
+   bunch of your handlers take the same query parameters, you shouldn't have to
+   repeat that logic for each handler, but instead just "apply" it to all of
+   them at once. Your handlers shouldn't be where composition goes to die. And
+   so on.
+
+- flexibility
+
+   If we haven't thought of your use case, it should still be easily
+   achievable. If you want to use templating library X, go ahead. Forms? Do
+   them however you want, but without difficulty. We're not opinionated.
+
+- separation of concerns
+
+   Your handlers and your HTTP logic should be separate. True to the philosphy
+   at the core of HTTP and REST, with *servant* your handlers return normal
+   Haskell datatypes - that's the resource. And then from a description of your
+   API, *servant* handles the *presentation* (i.e., the Content-Types). But
+   that's just one example.
+
+- type safety
+
+   Want to be sure your API meets a specification? Your compiler can check
+   that for you. Links you can be sure exist? You got it.
+
+To stick true to these principles, we do things a little differently than you
+might expect. The core idea is *reifying the description of your API*. Once
+reified, everything follows. We think we might be the first web framework to
+reify API descriptions in an extensible way. We're pretty sure we're the first
+to reify it as *types*.
+
+To be able to write a webservice you only need to read the first two sections,
+but the goal of this document being to get you started with servant, we also
+cover the couple of ways you can extend servant for a great good.

doc/links.rst

@@ -0,0 +1,34 @@
+
+Helpful Links
+-------------
+
+- the central documentation (this site):
+  `haskell-servant.readthedocs.org <http://haskell-servant.readthedocs.org/>`_
+
+- the github repo:
+  `github.com/haskell-servant/servant <https://github.com/haskell-servant/servant>`_
+
+- the issue tracker (Feel free to create issues and submit PRs!):
+  `https://github.com/haskell-servant/servant/issues <https://github.com/haskell-servant/servant/issues>`_
+
+- the irc channel:
+  #servant on freenode
+
+- the mailing list:
+  `groups.google.com/forum/#!forum/haskell-servant <https://groups.google.com/forum/#!forum/haskell-servant>`_
+
+- blog posts and videos and slides of some talks on servant:
+  `haskell-servant.github.io <http://haskell-servant.github.io>`_
+
+- the servant packages on hackage:
+
+  - `hackage.haskell.org/package/servant <http://hackage.haskell.org/package/servant>`_
+  - `hackage.haskell.org/package/servant-server <http://hackage.haskell.org/package/servant-server>`_
+  - `hackage.haskell.org/package/servant-client <http://hackage.haskell.org/package/servant-client>`_
+  - `hackage.haskell.org/package/servant-blaze <http://hackage.haskell.org/package/servant-blaze>`_
+  - `hackage.haskell.org/package/servant-lucid <http://hackage.haskell.org/package/servant-lucid>`_
+  - `hackage.haskell.org/package/servant-cassava <http://hackage.haskell.org/package/servant-cassava>`_
+  - `hackage.haskell.org/package/servant-docs <http://hackage.haskell.org/package/servant-docs>`_
+  - `hackage.haskell.org/package/servant-foreign <http://hackage.haskell.org/package/servant-foreign>`_
+  - `hackage.haskell.org/package/servant-js <http://hackage.haskell.org/package/servant-js>`_
+  - `hackage.haskell.org/package/servant-mock <http://hackage.haskell.org/package/servant-mock>`_

doc/tutorial/index.rst

@@ -1,64 +1,10 @@
-Servant tutorial
-================
+Tutorial
+========
 
 This is an introductory tutorial to the current version of *servant*, which is
 **0.4**. Any comment or issue can be directed to `this website's issue
 tracker <http://github.com/haskell-servant/haskell-servant.github.io/issues>`_.
 
-Github
--------
-
-- the servant packages: `haskell-servant/servant <https://github.com/haskell-servant/servant>`_
-- the website (including this tutorial): `haskell-servant/haskell-servant.github.io <https://github.com/haskell-servant/haskell-servant.github.io/>`_
-- Feel free to use the issue tracker (or to send PRs!) on the website's repository to give feedback and suggestions about this tutorial
-
-Introduction
--------------
-
-*servant* has the following guiding principles:
-
-- concision
-
-   This is a pretty wide-ranging principle. You should be able to get nice
-   documentation for your web servers, and client libraries, without repeating
-   yourself. You should not have to manually serialize and deserialize your
-   resources, but only declare how to do those things *once per type*. If a
-   bunch of your handlers take the same query parameters, you shouldn't have to
-   repeat that logic for each handler, but instead just "apply" it to all of
-   them at once. Your handlers shouldn't be where composition goes to die. And
-   so on.
-
-- flexibility
-
-   If we haven't thought of your use case, it should still be easily
-   achievable. If you want to use templating library X, go ahead. Forms? Do
-   them however you want, but without difficulty. We're not opinionated.
-
-- separation of concerns
-
-   Your handlers and your HTTP logic should be separate. True to the philosphy
-   at the core of HTTP and REST, with *servant* your handlers return normal
-   Haskell datatypes - that's the resource. And then from a description of your
-   API, *servant* handles the *presentation* (i.e., the Content-Types). But
-   that's just one example.
-
-- type safety
-
-   Want to be sure your API meets a specification? Your compiler can check
-   that for you. Links you can be sure exist? You got it.
-
-To stick true to these principles, we do things a little differently than you
-might expect. The core idea is *reifying the description of your API*. Once
-reified, everything follows. We think we might be the first web framework to
-reify API descriptions in an extensible way. We're pretty sure we're the first
-to reify it as *types*.
-
-To be able to write a webservice you only need to read the first two sections,
-but the goal of this document being to get you started with servant, we also
-cover the couple of ways you can extend servant for a great good.
-
-Tutorial
----------
 
 .. toctree::
   :maxdepth: 1