git.iko.soy/typeable/servant
on master help sign in
Moved tutorial to servant-examples/tutorial and include it in doc/index.rst
commit1d4e3a1e5b88aa7b54802a7e40aa606a5126c391 authorSönke Hahn <soenkehahn@gmail.com> dateMon 25 Jan 2016, 22:30 (11 years ago) parent7bb393f
19 files changed+13−545
.gitignore+1−1 tutorial/Makefile → doc/Makefile doc/conf.py+8−7 doc/index.rst+2−1 tutorial/requirements.txt → doc/requirements.txt doc/tutorial+1 servant-examples/tutorial/T8.hs−49 tutorial/api-type.lhs → servant-examples/tutorial/api-type.lhs tutorial/client.lhs → servant-examples/tutorial/client.lhs tutorial/docs.lhs → servant-examples/tutorial/docs.lhs tutorial/index.rst → servant-examples/tutorial/index.rst+1−1 tutorial/javascript.lhs → servant-examples/tutorial/javascript.lhs tutorial/server.lhs → servant-examples/tutorial/server.lhs servant-examples/tutorial/t8-main.hs−4 servant-examples/tutorial/t9/index.html−26 servant-examples/tutorial/t9/ui.js−61 servant-examples/tutorial/tutorial.hs−39 tutorial/conf.py−288 tutorial/index.md−68
.gitignore+1−1
@@ -25,4 +25,4 @@ Setup
2525.stack-work
2626shell.nix
2727default.nix
28−tutorial/_build
28+doc/_build
tutorial/Makefile → doc/Makefilerenamed

The content is the same.

doc/conf.py+8−7
@@ -37,7 +37,7 @@ templates_path = ['_templates']
3737
3838# The suffix(es) of source filenames.
3939# You can specify multiple suffix as a list of string:
40−source_suffix = ['.md', '.rst']
40+source_suffix = ['.md', '.rst', '.lhs']
4141
4242# The encoding of source files.
4343#source_encoding = 'utf-8-sig'
@@ -47,8 +47,8 @@ master_doc = 'index'
4747
4848# General information about the project.
4949project = u'servant'
50−copyright = u'2015-2016, Servant contributors'
51−author = u'Servant contributors'
50+copyright = u'2016, Servant Contributors'
51+author = u'Servant Contributors'
5252
5353# The version info for the project you're documenting, acts as replacement for
5454# |version| and |release|, also used in various other places throughout the
@@ -74,7 +74,7 @@ language = None
7474
7575# List of patterns, relative to source directory, that match files and
7676# directories to ignore when looking for source files.
77−exclude_patterns = ['_build']
77+exclude_patterns = ['_build', 'venv']
7878
7979# The reST default role (used for this markup: `text`) to use for all
8080# documents.
@@ -108,7 +108,7 @@ todo_include_todos = False
108108
109109# The theme to use for HTML and HTML Help pages. See the documentation for
110110# a list of builtin themes.
111−# html_theme = 'alabaster'
111+html_theme = 'sphinx_rtd_theme'
112112
113113# Theme options are theme-specific and customize the look and feel of a theme
114114# further. For a list of options available for each theme, see the
@@ -222,8 +222,8 @@ latex_elements = {
222222# (source start file, target name, title,
223223# author, documentclass [howto, manual, or own class]).
224224latex_documents = [
225− (master_doc, 'servant.tex', u'servant Documentation',
226− u'Servant contributors', 'manual'),
225+ (master_doc, 'servant.tex', u'servant Documentation',
226+ u'Servant Contributors', 'manual'),
227227]
228228
229229# The name of an image file (relative to this directory) to place at the top of
@@ -285,4 +285,5 @@ texinfo_documents = [
285285
286286source_parsers = {
287287 '.md': CommonMarkParser,
288+ '.lhs': CommonMarkParser,
288289}
doc/index.rst+2−1
@@ -5,7 +5,8 @@ Documentation table of contents
55-------------------------------
66
77.. toctree::
8+ :maxdepth: 2
89
910 README.md
11+ tutorial/index.rst
1012 CONTRIBUTING.md
11−
tutorial/requirements.txt → doc/requirements.txtrenamed

The content is the same.

doc/tutorialnew file+1
@@ -0,0 +1 @@
1+../servant-examples/tutorial
servant-examples/tutorial/T8.hsdeleted−49
@@ -1,49 +0,0 @@
1−{-# LANGUAGE DataKinds #-}
2−{-# LANGUAGE TypeFamilies #-}
3−{-# LANGUAGE TypeOperators #-}
4−module T8 where
5−
6−import Control.Monad.Trans.Except
7−import Network.HTTP.Client (Manager, defaultManagerSettings,
8− newManager)
9−import Servant
10−import Servant.Client
11−import System.IO.Unsafe (unsafePerformIO)
12−
13−import T3
14−
15−position :: Int -- ^ value for "x"
16− -> Int -- ^ value for "y"
17− -> ExceptT ServantError IO Position
18−
19−hello :: Maybe String -- ^ an optional value for "name"
20− -> ExceptT ServantError IO HelloMessage
21−
22−marketing :: ClientInfo -- ^ value for the request body
23− -> ExceptT ServantError IO Email
24−
25−position :<|> hello :<|> marketing = client api baseUrl manager
26−
27−baseUrl :: BaseUrl
28−baseUrl = BaseUrl Http "localhost" 8081 ""
29−
30−{-# NOINLINE manager #-}
31−manager :: Manager
32−manager = unsafePerformIO $ newManager defaultManagerSettings
33−
34−queries :: ExceptT ServantError IO (Position, HelloMessage, Email)
35−queries = do
36− pos <- position 10 10
37− msg <- hello (Just "servant")
38− em <- marketing (ClientInfo "Alp" "alp@foo.com" 26 ["haskell", "mathematics"])
39− return (pos, msg, em)
40−
41−run :: IO ()
42−run = do
43− res <- runExceptT queries
44− case res of
45− Left err -> putStrLn $ "Error: " ++ show err
46− Right (pos, msg, em) -> do
47− print pos
48− print msg
49− print em
tutorial/api-type.lhs → servant-examples/tutorial/api-type.lhsrenamed

The content is the same.

tutorial/client.lhs → servant-examples/tutorial/client.lhsrenamed

The content is the same.

tutorial/docs.lhs → servant-examples/tutorial/docs.lhsrenamed

The content is the same.

tutorial/index.rst → servant-examples/tutorial/index.rstrenamed+1−1
@@ -59,7 +59,7 @@ Tutorial
5959---------
6060
6161.. toctree::
62− :maxdepth: 2
62+ :maxdepth: 1
6363
6464 api-type.lhs
6565 server.lhs
tutorial/javascript.lhs → servant-examples/tutorial/javascript.lhsrenamed

The content is the same.

tutorial/server.lhs → servant-examples/tutorial/server.lhsrenamed

The content is the same.

servant-examples/tutorial/t8-main.hsdeleted−4
@@ -1,4 +0,0 @@
1−import T8
2−
3−main :: IO ()
4−main = run
servant-examples/tutorial/t9/index.htmldeleted−26
@@ -1,26 +0,0 @@
1−<!DOCTYPE html>
2−<html lang="en">
3− <head>
4− <meta name="viewport" content="width=device-width, initial-scale=1">
5− <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6− <title>Tutorial - 9 - servant-jquery</title>
7− </head>
8− <body>
9− <h1>Books</h1>
10− <input type="search" name="q" id="q" placeholder="Search author or book title..." />
11− <div>
12− <p>Results for <strong id="query">""</strong></p>
13− <ul id="results">
14− </ul>
15− </div>
16− <hr />
17− <h1>Approximating &pi;</h1>
18− <p>Count: <span id="count">0</span></p>
19− <p>Successes: <span id="successes">0</span></p>
20− <p id="pi"></p>
21−
22− <script type="text/javascript" src="/jq.js"></script>
23− <script type="text/javascript" src="/api.js"></script>
24− <script type="text/javascript" src="/ui.js"></script>
25−
26− </body>
servant-examples/tutorial/t9/ui.jsdeleted−61
@@ -1,61 +0,0 @@
1−/* book search */
2−function updateResults(data)
3−{
4− console.log(data);
5− $('#results').html("");
6− $('#query').text("\"" + data.query + "\"");
7− for(var i = 0; i < data.results.length; i++)
8− {
9− $('#results').append(renderBook(data.results[i]));
10− }
11−}
12−
13−function renderBook(book)
14−{
15− var li = '<li><strong>' + book.title + '</strong>, <i>'
16− + book.author + '</i> - ' + book.year + '</li>';
17− return li;
18−}
19−
20−function searchBooks()
21−{
22− var q = $('#q').val();
23− getBooks(q, updateResults, console.log)
24−}
25−
26−searchBooks();
27−$('#q').keyup(function() {
28− searchBooks();
29−});
30−
31−/* approximating pi */
32−var count = 0;
33−var successes = 0;
34−
35−function f(data)
36−{
37− var x = data.x, y = data.y;
38− if(x*x + y*y <= 1)
39− {
40− successes++;
41− }
42−
43− count++;
44−
45− update('#count', count);
46− update('#successes', successes);
47− update('#pi', 4*successes/count);
48−}
49−
50−function update(id, val)
51−{
52− $(id).text(val);
53−}
54−
55−function refresh()
56−{
57− getPoint(f, console.log);
58−}
59−
60−window.setInterval(refresh, 200);
61−
servant-examples/tutorial/tutorial.hsdeleted−39
@@ -1,39 +0,0 @@
1−import Network.Wai
2−import Network.Wai.Handler.Warp
3−import System.Environment
4−
5−import qualified T1
6−import qualified T10
7−import qualified T2
8−import qualified T3
9−import qualified T4
10−import qualified T5
11−import qualified T6
12−import qualified T7
13−import qualified T9
14−
15−app :: String -> (Application -> IO ()) -> IO ()
16−app n f = case n of
17− "1" -> f T1.app
18− "2" -> f T2.app
19− "3" -> f T3.app
20− "4" -> f T4.app
21− "5" -> f T5.app
22− "6" -> f T6.app
23− "7" -> f T7.app
24− "8" -> f T3.app
25− "9" -> T9.writeJSFiles >> f T9.app
26− "10" -> f T10.app
27− _ -> usage
28−
29−main :: IO ()
30−main = do
31− args <- getArgs
32− case args of
33− [n] -> app n (run 8081)
34− _ -> usage
35−
36−usage :: IO ()
37−usage = do
38− putStrLn "Usage:\t tutorial N"
39− putStrLn "\t\twhere N is the number of the example you want to run."
tutorial/conf.pydeleted−288
@@ -1,288 +0,0 @@
1−# -*- coding: utf-8 -*-
2−#
3−# servant documentation build configuration file, created by
4−# sphinx-quickstart on Fri Jan 22 12:22:48 2016.
5−#
6−# This file is execfile()d with the current directory set to its
7−# containing dir.
8−#
9−# Note that not all possible configuration values are present in this
10−# autogenerated file.
11−#
12−# All configuration values have a default; values that are commented out
13−# serve to show the default.
14−
15−import sys
16−import os
17−from recommonmark.parser import CommonMarkParser
18−
19−# If extensions (or modules to document with autodoc) are in another directory,
20−# add these directories to sys.path here. If the directory is relative to the
21−# documentation root, use os.path.abspath to make it absolute, like shown here.
22−#sys.path.insert(0, os.path.abspath('.'))
23−
24−# -- General configuration ------------------------------------------------
25−
26−# If your documentation needs a minimal Sphinx version, state it here.
27−#needs_sphinx = '1.0'
28−
29−# Add any Sphinx extension module names here, as strings. They can be
30−# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
31−# ones.
32−extensions = []
33−
34−# Add any paths that contain templates here, relative to this directory.
35−templates_path = ['_templates']
36−
37−# The suffix(es) of source filenames.
38−# You can specify multiple suffix as a list of string:
39−source_suffix = ['.md', '.rst', '.lhs']
40−
41−# The encoding of source files.
42−#source_encoding = 'utf-8-sig'
43−
44−# The master toctree document.
45−master_doc = 'index'
46−
47−# General information about the project.
48−project = u'servant'
49−copyright = u'2016, Servant Contributors'
50−author = u'Servant Contributors'
51−
52−# The version info for the project you're documenting, acts as replacement for
53−# |version| and |release|, also used in various other places throughout the
54−# built documents.
55−#
56−# The short X.Y version.
57−version = u'0.1'
58−# The full version, including alpha/beta/rc tags.
59−release = u'0.1'
60−
61−# The language for content autogenerated by Sphinx. Refer to documentation
62−# for a list of supported languages.
63−#
64−# This is also used if you do content translation via gettext catalogs.
65−# Usually you set "language" from the command line for these cases.
66−language = None
67−
68−# There are two options for replacing |today|: either, you set today to some
69−# non-false value, then it is used:
70−#today = ''
71−# Else, today_fmt is used as the format for a strftime call.
72−#today_fmt = '%B %d, %Y'
73−
74−# List of patterns, relative to source directory, that match files and
75−# directories to ignore when looking for source files.
76−exclude_patterns = ['_build', 'venv']
77−
78−# The reST default role (used for this markup: `text`) to use for all
79−# documents.
80−#default_role = None
81−
82−# If true, '()' will be appended to :func: etc. cross-reference text.
83−#add_function_parentheses = True
84−
85−# If true, the current module name will be prepended to all description
86−# unit titles (such as .. function::).
87−#add_module_names = True
88−
89−# If true, sectionauthor and moduleauthor directives will be shown in the
90−# output. They are ignored by default.
91−#show_authors = False
92−
93−# The name of the Pygments (syntax highlighting) style to use.
94−pygments_style = 'sphinx'
95−
96−# A list of ignored prefixes for module index sorting.
97−#modindex_common_prefix = []
98−
99−# If true, keep warnings as "system message" paragraphs in the built documents.
100−#keep_warnings = False
101−
102−# If true, `todo` and `todoList` produce output, else they produce nothing.
103−todo_include_todos = False
104−
105−
106−# -- Options for HTML output ----------------------------------------------
107−
108−# The theme to use for HTML and HTML Help pages. See the documentation for
109−# a list of builtin themes.
110−html_theme = 'sphinx_rtd_theme'
111−
112−# Theme options are theme-specific and customize the look and feel of a theme
113−# further. For a list of options available for each theme, see the
114−# documentation.
115−#html_theme_options = {}
116−
117−# Add any paths that contain custom themes here, relative to this directory.
118−#html_theme_path = []
119−
120−# The name for this set of Sphinx documents. If None, it defaults to
121−# "<project> v<release> documentation".
122−#html_title = None
123−
124−# A shorter title for the navigation bar. Default is the same as html_title.
125−#html_short_title = None
126−
127−# The name of an image file (relative to this directory) to place at the top
128−# of the sidebar.
129−#html_logo = None
130−
131−# The name of an image file (within the static path) to use as favicon of the
132−# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
133−# pixels large.
134−#html_favicon = None
135−
136−# Add any paths that contain custom static files (such as style sheets) here,
137−# relative to this directory. They are copied after the builtin static files,
138−# so a file named "default.css" will overwrite the builtin "default.css".
139−html_static_path = ['_static']
140−
141−# Add any extra paths that contain custom files (such as robots.txt or
142−# .htaccess) here, relative to this directory. These files are copied
143−# directly to the root of the documentation.
144−#html_extra_path = []
145−
146−# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
147−# using the given strftime format.
148−#html_last_updated_fmt = '%b %d, %Y'
149−
150−# If true, SmartyPants will be used to convert quotes and dashes to
151−# typographically correct entities.
152−#html_use_smartypants = True
153−
154−# Custom sidebar templates, maps document names to template names.
155−#html_sidebars = {}
156−
157−# Additional templates that should be rendered to pages, maps page names to
158−# template names.
159−#html_additional_pages = {}
160−
161−# If false, no module index is generated.
162−#html_domain_indices = True
163−
164−# If false, no index is generated.
165−#html_use_index = True
166−
167−# If true, the index is split into individual pages for each letter.
168−#html_split_index = False
169−
170−# If true, links to the reST sources are added to the pages.
171−#html_show_sourcelink = True
172−
173−# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
174−#html_show_sphinx = True
175−
176−# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
177−#html_show_copyright = True
178−
179−# If true, an OpenSearch description file will be output, and all pages will
180−# contain a <link> tag referring to it. The value of this option must be the
181−# base URL from which the finished HTML is served.
182−#html_use_opensearch = ''
183−
184−# This is the file name suffix for HTML files (e.g. ".xhtml").
185−#html_file_suffix = None
186−
187−# Language to be used for generating the HTML full-text search index.
188−# Sphinx supports the following languages:
189−# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
190−# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
191−#html_search_language = 'en'
192−
193−# A dictionary with options for the search language support, empty by default.
194−# Now only 'ja' uses this config value
195−#html_search_options = {'type': 'default'}
196−
197−# The name of a javascript file (relative to the configuration directory) that
198−# implements a search results scorer. If empty, the default will be used.
199−#html_search_scorer = 'scorer.js'
200−
201−# Output file base name for HTML help builder.
202−htmlhelp_basename = 'servantdoc'
203−
204−# -- Options for LaTeX output ---------------------------------------------
205−
206−latex_elements = {
207−# The paper size ('letterpaper' or 'a4paper').
208−#'papersize': 'letterpaper',
209−
210−# The font size ('10pt', '11pt' or '12pt').
211−#'pointsize': '10pt',
212−
213−# Additional stuff for the LaTeX preamble.
214−#'preamble': '',
215−
216−# Latex figure (float) alignment
217−#'figure_align': 'htbp',
218−}
219−
220−# Grouping the document tree into LaTeX files. List of tuples
221−# (source start file, target name, title,
222−# author, documentclass [howto, manual, or own class]).
223−latex_documents = [
224− (master_doc, 'servant.tex', u'servant Documentation',
225− u'Servant Contributors', 'manual'),
226−]
227−
228−# The name of an image file (relative to this directory) to place at the top of
229−# the title page.
230−#latex_logo = None
231−
232−# For "manual" documents, if this is true, then toplevel headings are parts,
233−# not chapters.
234−#latex_use_parts = False
235−
236−# If true, show page references after internal links.
237−#latex_show_pagerefs = False
238−
239−# If true, show URL addresses after external links.
240−#latex_show_urls = False
241−
242−# Documents to append as an appendix to all manuals.
243−#latex_appendices = []
244−
245−# If false, no module index is generated.
246−#latex_domain_indices = True
247−
248−
249−# -- Options for manual page output ---------------------------------------
250−
251−# One entry per manual page. List of tuples
252−# (source start file, name, description, authors, manual section).
253−man_pages = [
254− (master_doc, 'servant', u'servant Documentation',
255− [author], 1)
256−]
257−
258−# If true, show URL addresses after external links.
259−#man_show_urls = False
260−
261−
262−# -- Options for Texinfo output -------------------------------------------
263−
264−# Grouping the document tree into Texinfo files. List of tuples
265−# (source start file, target name, title, author,
266−# dir menu entry, description, category)
267−texinfo_documents = [
268− (master_doc, 'servant', u'servant Documentation',
269− author, 'servant', 'One line description of project.',
270− 'Miscellaneous'),
271−]
272−
273−# Documents to append as an appendix to all manuals.
274−#texinfo_appendices = []
275−
276−# If false, no module index is generated.
277−#texinfo_domain_indices = True
278−
279−# How to display URL addresses: 'footnote', 'no', or 'inline'.
280−#texinfo_show_urls = 'footnote'
281−
282−# If true, do not generate a @detailmenu in the "Top" node's menu.
283−#texinfo_no_detailmenu = False
284−
285−source_parsers = {
286− '.md': CommonMarkParser,
287− '.lhs': CommonMarkParser,
288−}
tutorial/index.mddeleted−68
@@ -1,68 +0,0 @@
1−Servant tutorial
2−================
3−
4−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).
5−
6−Github
7−-------
8−
9−- the servant packages: [haskell-servant/servant](https://github.com/haskell-servant/servant)
10−- the website (including this tutorial): [haskell-servant/haskell-servant.github.io](https://github.com/haskell-servant/haskell-servant.github.io/)
11−- Feel free to use the issue tracker (or to send PRs!) on the website's repository to give feedback and suggestions about this tutorial
12−
13−Introduction
14−-------------
15−
16−*servant* has the following guiding principles:
17−
18−- concision
19−
20− This is a pretty wide-ranging principle. You should be able to get nice
21− documentation for your web servers, and client libraries, without repeating
22− yourself. You should not have to manually serialize and deserialize your
23− resources, but only declare how to do those things *once per type*. If a
24− bunch of your handlers take the same query parameters, you shouldn't have to
25− repeat that logic for each handler, but instead just "apply" it to all of
26− them at once. Your handlers shouldn't be where composition goes to die. And
27− so on.
28−
29−- flexibility
30−
31− If we haven't thought of your use case, it should still be easily
32− achievable. If you want to use templating library X, go ahead. Forms? Do
33− them however you want, but without difficulty. We're not opinionated.
34−
35−- separation of concerns
36−
37− Your handlers and your HTTP logic should be separate. True to the philosphy
38− at the core of HTTP and REST, with *servant* your handlers return normal
39− Haskell datatypes - that's the resource. And then from a description of your
40− API, *servant* handles the *presentation* (i.e., the Content-Types). But
41− that's just one example.
42−
43−- type safety
44−
45− Want to be sure your API meets a specification? Your compiler can check
46− that for you. Links you can be sure exist? You got it.
47−
48−To stick true to these principles, we do things a little differently than you
49−might expect. The core idea is *reifying the description of your API*. Once
50−reified, everything follows. We think we might be the first web framework to
51−reify API descriptions in an extensible way. We're pretty sure we're the first
52−to reify it as *types*.
53−
54−To be able to write a webservice you only need to read the first two sections,
55−but the goal of this document being to get you started with servant, we also
56−cover the couple of ways you can extend servant for a great good.
57−
58−Tutorial
59−---------
60−
61−.. toctree::
62− :maxdepth: 2
63−
64− api-type.lhs
65− server.lhs
66− client.lhs
67− javascript.lhs
68− docs.lhs