Merge pull request #22 from f/master

Add documentation.
2024-08-15 00:53:36 +00:00 · 2015-12-04 14:26:55 +02:00 · 2015-12-04 14:26:55 +02:00 · 564cdcac0b
commit 564cdcac0b
parent 7e04f51e3c 60c3a15ee4
6 changed files with 204 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,33 @@
+# Kemal Documentation
+
+This README includes documentation of Kemal, the Crystal Web Framework.
+
+## What is Kemal?
+
+Kemal is a web server working on Crystal language. Strongly inspired on Sinatra project.
+_Needs more info_
+
+## What is Crystal?
+
+Crystal is a programming language based on *Ruby* syntax.
+
+## Advantages of using Kemal
+
+ - Too easy to learn and start to develop.
+ - Since it's working on LLVM, it's too fast.
+ - You can deploy it on *Heroku*.
+
+## The Name
+
+Kemal means *Mature, grown up* in Turkish and Arabic.
+
+## How to start?
+
+ - [Getting Started Tutorial](./tutorial.md)
+ - [Using Dynamic Templates (Not Supported Yet)](./templates.md)
+ - [Parsing HTTP requests and Form Data](./http-requests.md)
+ - [Uploading Files](./upload.md)
+ - [Serving Static Files](./statics.md)
+ - [Serving JSON API](./json.md)
+ - [Restful Web Services](./rest.md)
+ - [How to connect to Database](./database.md)
--- a/docs/http-requests.md
+++ b/docs/http-requests.md
@ -0,0 +1,40 @@
+# HTTP Requests
+
+You should use `env` variable to handle HTTP params. For both `get` and `post` (and others) methods, you should use `env` object.
+
+```ruby
+# Matches /hello/kemal
+  get "/hello/:name" do |env|
+    name = env.params["name"]
+    "Hello back to #{name}"
+  end
+
+  # Matches /resize?width=200&height=200
+  get "/resize" do |env|
+    width = env.params["width"]
+    height = env.params["height"]
+  end
+
+  # Easily access JSON payload from the params.
+  # The request content type needs to be application/json
+  # The payload
+  # {"name": "Serdar", "likes": ["Ruby", "Crystal"]}
+  post "/json_params" do |env|
+    name = env.params["name"] as String
+    likes = env.params["likes"] as Array
+    "#{name} likes #{likes.each.join(',')}"
+  end
+
+  # Set the content as application/json and return JSON
+  get "/user.json" do |env|
+    kemal = {name: "Kemal", language: "Crystal"}
+    env.content_type = "application/json"
+    kemal.to_json
+  end
+
+  # Add headers to your response
+  get "/headers" do |env|
+    env.add_header "Accept-Language", "tr"
+    env.add_header "Authorization", "Token 12345"
+  end
+```
--- a/docs/json.md
+++ b/docs/json.md
@ -0,0 +1,16 @@
+# Serving JSON API
+
+Just use `to_json` method to return.
+
+```ruby
+require "kemal"
+require "json"
+
+# You can easily access the context and set content_type like 'application/json'.
+# Look how easy to build a JSON serving API.
+get "/" do |env|
+  env.content_type = "application/json"
+  {name: "Serdar", age: 27}.to_json
+end
+
+```
--- a/docs/rest.md
+++ b/docs/rest.md
@ -0,0 +1,25 @@
+# Restful Web Services
+
+You can handle HTTP methods as easy as writing method names and the route with a code block. Kemal will handle all the hard work.
+
+```
+  get "/" do
+  .. show something ..
+  end
+
+  post "/" do
+  .. create something ..
+  end
+
+  put "/" do
+  .. replace something ..
+  end
+
+  patch "/" do
+  .. modify something ..
+  end
+
+  delete "/" do
+  .. annihilate something ..
+  end  
+```
--- a/docs/statics.md
+++ b/docs/statics.md
@ -0,0 +1,31 @@
+# Statics
+
+Add your files to `public` directory and Kemal will serve these files immediately.
+
+```
+app/
+  src/
+    awesome_web_project.cr
+  public/
+    js/
+      jquery.js
+      awesome_web_project.js
+    css/
+      awesome_web_project.css
+    index.html
+```
+
+Open index.html and add
+
+```html
+<html>
+ <head>
+   <script src="/js/jquery.js"></script>
+   <script src="/js/awesome_web_project.js"></script>
+   <link rel="stylesheet" href="/css/awesome_web_project.css"/>
+ </head>
+ <body>
+   ...
+ </body>
+</html>
+```
--- a/docs/tutorial.md
+++ b/docs/tutorial.md
@ -0,0 +1,59 @@
+# Kemal Tutorial
+
+## Install Crystal
+
+```
+brew update
+brew install crystal-lang
+```
+
+## Installing Kemal
+
+You should create your application first:
+
+```
+crystal init app awesome_web_project
+cd awesome_web_project
+```
+
+Then add *kemal* to the `shard.yml` file as a dependency.
+
+```yml
+dependencies:
+  kemal:
+    github: sdogruyol/kemal
+    branch: master
+```
+
+You should run `shards` to get dependencies:
+
+```
+shards install
+```
+
+## Include Kemal into your project
+
+Open `awesome_web_project/src/awesome_web_project.cr` and require `kemal` to use Kemal.
+
+```ruby
+require 'kemal'
+```
+
+## Hack your project
+
+Do some awesome stuff with awesome Kemal.
+
+```ruby
+get "/" do
+  "Hello World!"
+end
+```
+
+## Run your awesome web project.
+
+```
+crystal build --release src/awesome_web_project.cr
+./awesome_web_project
+```
+
+Now you can be happy with your new, very fast, readable web project.