📝 Add docs, set up mkdocs

docs/features.md

@@ -0,0 +1,113 @@
+
+## FastAPI features
+
+**FastAPI** gives you the following:
+
+* Automatic API documentation with the open standard: <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank"><strong>OpenAPI</strong></a>.
+* Automatic data model documentation with <a href="http://json-schema.org/" target="_blank"><strong>JSON Schema</strong></a> (as OpenAPI itself is based on JSON Schema).
+* Interactive API documentation and exploration web user interface with <a href="https://github.com/swagger-api/swagger-ui" target="_blank"><strong>Swagger UI</strong></a>.
+
+![Swagger UI interaction](img/readme-assets/readme05.png)
+
+* Alternative API documentation with <a href="https://github.com/Rebilly/ReDoc" target="_blank"><strong>ReDoc</strong></a>.
+
+![ReDoc](img/readme-assets/readme06.png)
+
+
+* All based on standard **Python 3.6 type** declarations (thanks to Pydantic). No new syntax to learn:
+
+```Python
+from typing import List, Dict
+from datetime import date
+
+from pydantic import BaseModel
+
+# Declare a variable as an int
+user_id: int
+
+# Declare the type and set a value
+user_id: int = 3
+
+# tags is a list of str
+tags: List[str] = ["fast", "easy", "short", "robust"]
+
+
+# item_tags is a dict with str as keys, and lists of str as values
+item_tags: Dict[str, List[str]] = {
+    "foo": ["The Foo", "Foo Fighters"], 
+    "bar": ["Bar Halen", "Bars N' Roses"]
+    }
+
+# A Pydantic model
+class User(BaseModel):
+    id: int
+    name: str
+    joined: datetime
+
+
+my_user: User = User(id=3, name="John Doe", joined="2018-07-19")
+
+second_user_data = {
+    "id": 4,
+    "name": "Mary",
+    "joined": "2018-11-30",
+}
+
+
+# **second_user_data means "pass the keys and values of the dict directly as arguments
+my_second_user: User = User(**second_user_data)
+```
+
+* Sensible **defaults** for everything, with optional configurations everywhere.
+* Validation for many **data types**, including JSON objects (`dict`) fields, JSON array (`list`) item types, string (`str`) min and max lengths, number (`int`, `float`) min and max values, etc.
+* Security and authentication included: all the security schemes defined in OpenAPI, including HTTP Basic, **OAuth2** (also with **JWT tokens**), API keys, etc. Plus the security features from Starlette (including session cookies). All built as reusable tools and components that are easy to integrate with your systems, data stores, databases, etc.
+* Extremely easy, but extremely powerful **Dependency Injection** (also known as "components", "resources", "services", "providers"):
+    * Even dependencies can have dependencies, creating a hierarchy or **"graph" of dependencies**.
+    * All **automatically handled** by the framework. 
+    * All the dependencies can **augment the endpoint** parameters and constraints.
+    * **Automatic validation** even for parameters from dependencies.
+    * Support for complex user authentication systems, **database connections**, etc.
+* **No compromise** with databases, frontends, etc. But easy integration with all.
+* **Unlimited "plug-ins"**:
+    * Or in other way, no need for them, import and use the code you need. 
+    * Any integration is designed to be so simple to use (with dependencies) that you can create a "plug-in" for your application in 2 lines of code.
+* Fully compatible with (and based on) **Starlette**.
+    * Any additional Starlette code you have, will also work.
+* Fully compatible with (and based on) **Pydantic**. 
+    * Any additional Pydantic code you have will also work.
+    * Including external libraries also based on Pydantic.
+* 100% test coverage (* not yet, in a couple days).
+* 100% type annotated code base.
+
+## Starlette features
+
+Plus **Starlette**'s features (FastAPI is just Starlette on steroids):
+
+* Seriously impressive performance. It is <a href="https://github.com/encode/starlette#performance" target="_blank">one of the fastest Python frameworks available, on par with **NodeJS** and **Go**</a>.
+* **WebSocket** support.
+* **GraphQL** support.
+* In-process background tasks.
+* Startup and shutdown events.
+* Test client built on `requests`.
+* **CORS**, GZip, Static Files, Streaming responses.
+* **Session and Cookie** support.
+* 100% test coverage.
+* 100% type annotated codebase.
+
+## Pydantic features
+
+Plus **Pydantic**'s features:
+
+* **No brainfuck**: 
+    * No new schema definition micro-language to learn.
+    * If you know Python types you know how to use Pydantic.
+* Plays nicely with your **IDE/linter/brain**:
+    * Because pydantic data structures are just instances of classes you define; auto-completion, linting, mypy and your intuition should all work properly with your validated data.
+* **Fast**:
+    * in <a href="https://pydantic-docs.helpmanual.io/#benchmarks-tag" target="_blank">benchmarks</a> Pydantic is faster than all other tested libraries.
+* Validate **complex structures**:
+    * Use of hierarchical Pydantic models, Python `typing`’s `List` and `Dict`, etc.
+    * And validators allow complex data schemas to be clearly and easily defined, checked and documented as JSON Schema.
+    * You can have deeply **nested JSON** objects and have them all validated and annotated.
+* **Extendible**:
+    * Pydantic allows custom data types to be defined or you can extend validation with methods on a model decorated with the validator decorator.

docs/index.md

@@ -0,0 +1,295 @@
+<p align="center">
+  <a href="https://fastapi.tiangolo.com"><img style="width: 70%;" src="img/logo-teal-vector.svg" alt='FastAPI'></a>
+</p>
+<p align="center">
+    <em>FastAPI framework, high performance, easy to learn, fast to code, ready for production</em>
+</p>
+<p align="center">
+<a href="https://travis-ci.org/tiangolo/fastapi">
+    <img src="https://travis-ci.org/tiangolo/fastapi.svg?branch=master" alt="Build Status">
+</a>
+<a href="https://codecov.io/gh/tiangolo/fastapi">
+    <img src="https://codecov.io/gh/tiangolo/fastapi/branch/master/graph/badge.svg" alt="Coverage">
+</a>
+<a href="https://pypi.org/project/fastapi">
+    <img src="https://badge.fury.io/py/fastapi.svg" alt="Package version">
+</a>
+</p>
+
+---
+
+**Documentation**: [https://fastapi.tiangolo.com](https://fastapi.tiangolo.com)
+
+---
+
+FastAPI is a modern, fast (high-performance), web framework for building APIs with Python 3.6+.
+
+The key features are:
+
+* **Fast**: Very high performance, on par with **NodeJS** and **Go**.
+* **Easy**: Designed to be easy to use and learn.
+* **Intuitive**: Great editor support. Completion (auto-complete, IntelliSense) everywhere.
+* **Short**: Minimize code duplication. Multiple features from each parameter declaration.
+* **Robust**: Get production-ready code. With automatic interactive documentation.
+* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank">OpenAPI</a> and <a href="http://json-schema.org/" target="_blank">JSON Schema</a>.
+
+
+## Requirements
+
+Python 3.6+
+
+FastAPI rests on the shoulders of giants:
+
+* <a href="https://www.starlette.io/" target="_blank">Starlette</a> for the web parts.
+* <a href="https://pydantic-docs.helpmanual.io/" target="_blank">Pydantic</a> for the data parts.
+
+
+## Installation
+
+```shell
+$ pip3 install fastapi
+```
+
+You will also need an ASGI server, for production such as <a href="http://www.uvicorn.org" target="_blank">uvicorn</a>.
+
+```shell
+$ pip3 install uvicorn
+```
+
+## Example
+
+* Create a file `main.py` with:
+
+```Python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get('/')
+async def read_root():
+    return {'hello': 'world'}
+```
+
+* Run the server with:
+
+```bash
+uvicorn main:app --debug
+```
+
+**Note**: the command `uvicorn main:app` refers to:
+
+* `main`: the file `main.py` (the Python "module").
+* `app`: the object created inside of `main.py` with the line `app = FastAPI()`.
+* `--debug`: make the server restart after code changes. Only use for development.
+
+### Check it
+
+Open your browser at <a href="http://127.0.0.1:8000" target="_blank">http://127.0.0.1:8000</a>. 
+
+You will see the JSON response as:
+
+```JSON
+{"hello": "world"}
+```
+
+### Interactive API docs
+
+Now go to <a href="http://127.0.0.1:8000/docs" target="_blank">http://127.0.0.1:8000/docs</a>. 
+
+You will see the automatic interactive API documentation (provided by <a href="https://github.com/swagger-api/swagger-ui" target="_blank">Swagger UI</a>):
+
+![Swagger UI](img/readme-assets/readme01.png)
+
+
+### Alternative API docs
+
+And now, go to <a href="http://127.0.0.1:8000/redoc" target="_blank">http://127.0.0.1:8000/redoc</a>.
+
+You will see the alternative automatic documentation (provided by <a href="https://github.com/Rebilly/ReDoc" target="_blank">ReDoc</a>):
+
+![ReDoc](img/readme-assets/readme02.png)
+
+## Example upgrade
+
+Now modify the file `main.py` to include:
+
+* a path parameter `item_id`.
+* a body, declared using standard Python types (thanks to Pydantic).
+* an optional query parameter `q`.
+
+
+```Python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+
+class Item(BaseModel):
+    name: str
+    price: float
+    is_offer: bool = None
+
+
+@app.get('/')
+async def read_root():
+    return {'hello': 'world'}
+
+
+@app.post('/items/{item_id}')
+async def create_item(item_id: int, item: Item, q: str = None):
+    return {"item_name": item.name, "item_id": item_id, "query": q}
+```
+
+The server should reload automatically (because you added `--debug` to the `uvicorn` command above).
+
+### Interactive API docs upgrade
+
+Now go to <a href="http://127.0.0.1:8000/docs" target="_blank">http://127.0.0.1:8000/docs</a>.
+
+* The interactive API documentation will be automatically updated, including the new query, and body:
+
+![Swagger UI](img/readme-assets/readme03.png)
+
+* Click on the button "Try it out", it allows you to fill the parameters and directly interact with the API:
+
+![Swagger UI interaction](img/readme-assets/readme04.png)
+
+* Then click on the "Execute" button, the user interface will communicate with your API, send the parameters, get the results and show them on the screen:
+
+![Swagger UI interaction](img/readme-assets/readme05.png)
+
+
+### Alternative API docs upgrade
+
+And now, go to <a href="http://127.0.0.1:8000/redoc" target="_blank">http://127.0.0.1:8000/redoc</a>.
+
+* The alternative documentation will also reflect the new query parameter and body:
+
+![ReDoc](img/readme-assets/readme06.png)
+
+
+### Recap
+
+In summary, you declare **once** the types of parameters, body, etc. as function parameters. You don't have to learn a new syntax, use a specific library, class or object to declare fields, you just type standard Python types.
+
+For example, for an `int`:
+
+```Python
+item_id: int
+```
+
+or for a more complex `Item` model:
+
+```Python
+item: Item
+```
+
+...and with that single declaration you get:
+
+* Editor support, including:
+    * Completion.
+    * Type checks.
+* Validation of data:
+    * Automatic and clear errors when the data is invalid.
+    * Validation even for deeply nested JSON objects.
+* Serialization of input data: from the network to Python, reading from:
+    * JSON.
+    * Forms.
+    * Files.
+    * Path parameters.
+    * Query parameters.
+    * Cookies.
+    * Headers.
+* Serialization of output data: from Python to network (as JSON):
+    * Convert Python types.
+    * `datetime` objects.
+    * `UUID` objects.
+    * Database models.
+    * ...and many more.
+* Automatic interactive API documentation, including 2 alternative user interfaces:
+    * Swagger UI.
+    * ReDoc.
+
+---
+
+Coming back to the previous code example, **FastAPI** will:
+
+* Validate that there is an `item_id` in the path.
+* Validate that the `item_id` is of type `int`. If it is not, the client will see a useful error.
+* Check if there is an optional query parameter named `q` (as in `http://127.0.0.1:8000/items/foo?q=somequery`). As the `q` parameter is declared with `= None`, it is optional. Without the `None` it would be required (as is the body).
+* Read the body as JSON:
+    * Check that it has a required attribute `name` that should be a `str`. 
+    * Check that is has a required attribute `price` that has to be a `float`.
+    * Check that it has an optional attribute `is_offer`, that should be a `bool`, if present.
+    * All this would also work for deeply nested JSON objects
+* Convert from and to JSON automatically.
+* Document everything as OpenAPI, so the interactive documentation is created and updated automatically.
+* Provide the interactive documentation web interfaces.
+
+
+---
+
+We just scratched the surface, but you already get the idea of how it all works.
+
+Try changing the line with:
+
+```Python
+    return {"item_name": item.name, "item_id": item_id, "query": q}
+```
+
+...from:
+
+```Python
+        ... "item_name": item.name ...
+```
+
+...to:
+
+```Python
+        ... "item_price": item.price ...
+```
+
+...and see how your editor will auto-complete the attributes and know their types:
+
+![editor support](img/vscode-completion.png)
+
+
+For a more complete example including more features, [see the tutorial](tutorial).
+
+**Spoiler alert**: the tutorial, although very short, includes:
+
+* Declaration of **parameters** from different places as: headers, cookies, form data and files.
+* How to set **validation constrains** as `maximum_length` or `regex`.
+* A very powerful and easy to use **Dependency Injection** system (also known as "components", "resources", "providers", "services").
+* Security and authentication, including support for **OAuth2** with **JWT tokens** and **HTTP Basic** auth.
+* More advanced (but equally easy) techniques for declaring **deeply nested models** (JSON body, Form and Files) (thanks to Pydantic).
+* Many extra features (thanks to Starlette) as **WebSockets**, **GraphQL**, extremely easy tests based on `requests` and `pytest`, CORS, Cookie Sessions and more.
+
+
+
+## Optional Dependencies
+
+Used by Pydantic:
+
+* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - for faster JSON parsing.
+* <a href="https://github.com/JoshData/python-email-validator" target="_blank"><code>email_validator</code></a> - for email validation.
+
+
+Used by Starlette:
+
+* <a href="http://docs.python-requests.org" target="_blank"><code>requests</code></a> - Required if you want to use the `TestClient`.
+* <a href="https://github.com/Tinche/aiofiles" target="_blank"><code>aiofiles</code></a> - Required if you want to use `FileResponse` or `StaticFiles`.
+* <a href="http://jinja.pocoo.org" target="_blank"><code>jinja2</code></a> - Required if you want to use the default template configuration.
+* <a href="https://andrew-d.github.io/python-multipart/" target="_blank"><code>python-multipart</code></a> - Required if you want to support form parsing, with `request.form()`.
+* <a href="https://pythonhosted.org/itsdangerous/" target="_blank"><code>itsdangerous</code></a> - Required for `SessionMiddleware` support.
+* <a href="https://pyyaml.org/wiki/PyYAMLDocumentation" target="_blank"><code>pyyaml</code></a> - Required for `SchemaGenerator` support.
+* <a href="https://graphene-python.org/" target="_blank"><code>graphene</code></a> - Required for `GraphQLApp` support.
+* <a href="https://github.com/esnme/ultrajson" target="_blank"><code>ujson</code></a> - Required if you want to use `UJSONResponse`.
+
+
+You can install all of these with `pip3 install fastapi[full]`.
+
+## License
+
+This project is licensed under the terms of the MIT license.

docs/tutorial/index.md

@@ -0,0 +1 @@
+Sorry! Coming soon... come back in a couple days.

mkdocs.yml

@@ -0,0 +1,26 @@
+site_name: FastAPI
+site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production
+
+theme:
+    name: 'material'
+    palette:
+      primary: 'teal'
+      accent: 'amber'
+    logo: 'img/icon-white.svg'
+    favicon: 'img/favicon.png'
+
+repo_name: tiangolo/fastapi
+repo_url: https://github.com/tiangolo/fastapi
+edit_uri: ""
+
+nav:
+    - Introduction: 'index.md'
+    - Tutorial: 'tutorial/index.md'
+    - Features: 'features.md'
+    
+
+markdown_extensions:
+  - markdown.extensions.codehilite:
+      guess_lang: false
+  - markdown_include.include:
+      base_path: docs

scripts/clean.sh

@@ -0,0 +1,8 @@
+#!/bin/sh -e
+
+if [ -d 'dist' ] ; then
+    rm -r dist
+fi
+if [ -d 'site' ] ; then
+    rm -r site
+fi

scripts/docs-live.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+set -e
+
+mkdocs --serve --dev-addr 0.0.0.0:8008