🔖 Release version 0.53.0

from shields.io, as Codecov's one shows coverage for the last PR from a fork at master

.github/workflows/deploy-docs.yml

@@ -16,8 +16,8 @@ jobs:
         run: python3.7 -m pip install flit
       - name: Install docs extras
         run: python3.7 -m flit install --extras doc
-      - name: Build MkDocs
-        run: python3.7 -m mkdocs build
+      - name: Build Docs
+        run: python3.7 ./scripts/docs.py build-all
       - name: Deploy to Netlify
         uses: nwtgck/actions-netlify@v1.0.3
         with:

.gitignore

@@ -14,3 +14,4 @@ test.db
 log.txt
 Pipfile.lock
 env3.*
+docs_build

README.md

@@ -9,7 +9,7 @@
     <img src="https://travis-ci.com/tiangolo/fastapi.svg?branch=master" alt="Build Status">
 </a>
 <a href="https://codecov.io/gh/tiangolo/fastapi" target="_blank">
-    <img src="https://codecov.io/gh/tiangolo/fastapi/branch/master/graph/badge.svg" alt="Coverage">
+    <img src="https://img.shields.io/codecov/c/github/tiangolo/fastapi" alt="Coverage">
 </a>
 <a href="https://pypi.org/project/fastapi" target="_blank">
     <img src="https://badge.fury.io/py/fastapi.svg" alt="Package version">
@@ -77,6 +77,14 @@ The key features are:
 
 ---
 
+## **Typer**, the FastAPI of CLIs
+
+<a href="https://typer.tiangolo.com" target="_blank"><img src="https://typer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" style="width: 20%;"></a>
+
+If you are building a <abbr title="Command Line Interface">CLI</abbr> app to be used in the terminal instead of a web API, check out <a href="https://typer.tiangolo.com/" class="external-link" target="_blank">**Typer**</a>.
+
+**Typer** is FastAPI's little sibling. And it's intended to be the **FastAPI of CLIs**. ⌨️ 🚀
+
 ## Requirements
 
 Python 3.6+
@@ -88,16 +96,28 @@ FastAPI stands on the shoulders of giants:
 
 ## Installation
 
-```bash
-pip install fastapi
+<div class="termy">
+
+```console
+$ pip install fastapi
+
+---> 100%
 ```
 
+</div>
+
 You will also need an ASGI server, for production such as <a href="http://www.uvicorn.org" class="external-link" target="_blank">Uvicorn</a> or <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>.
 
-```bash
-pip install uvicorn
+<div class="termy">
+
+```console
+$ pip install uvicorn
+
+---> 100%
 ```
 
+</div>
+
 ## Example
 
 ### Create it
@@ -151,10 +171,20 @@ If you don't know, check the _"In a hurry?"_ section about <a href="https://fast
 
 Run the server with:
 
-```bash
-uvicorn main:app --reload
+<div class="termy">
+
+```console
+$ uvicorn main:app --reload
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+<span style="color: green;">INFO</span>:     Started reloader process [28720]
+<span style="color: green;">INFO</span>:     Started server process [28722]
+<span style="color: green;">INFO</span>:     Waiting for application startup.
+<span style="color: green;">INFO</span>:     Application startup complete.
 ```
 
+</div>
+
 <details markdown="1">
 <summary>About the command <code>uvicorn main:app --reload</code>...</summary>
 
@@ -398,6 +428,7 @@ Used by Starlette:
 Used by FastAPI / Starlette:
 
 * <a href="http://www.uvicorn.org" target="_blank"><code>uvicorn</code></a> - for the server that loads and serves your application.
+* <a href="https://github.com/ijl/orjson" target="_blank"><code>orjson</code></a> - Required if you want to use `ORJSONResponse`.
 
 You can install all of these with `pip install fastapi[all]`.
 

docs/advanced/custom-response.md

@@ -1,102 +0,0 @@
-!!! warning
-    This is a rather advanced topic.
-
-    If you are starting with **FastAPI**, you might not need this.
-
-By default, **FastAPI** will return the responses using Starlette's `JSONResponse`.
-
-You can override it by returning a `Response` directly as seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}.
-
-But if you return a `Response` directly, the data won't be automatically converted, and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type`).
-
-But you can also declare the `Response` that you want to be used, in the *path operation decorator*.
-
-The contents that you return from your *path operation function* will be put inside of that `Response`.
-
-And if that `Response` has a JSON media type (`application/json`), like is the case with the `JSONResponse` and `UJSONResponse`, the data you return will be automatically converted (and filtered) with any Pydantic `response_model` that you declared in the *path operation decorator*.
-
-!!! note
-    If you use a response class with no media type, FastAPI will expect your response to have no content, so it will not document the response format in its generated OpenAPI docs.
-
-## Use `UJSONResponse`
-
-For example, if you are squeezing performance, you can install and use `ujson` and set the response to be Starlette's `UJSONResponse`.
-
-Import the `Response` class (sub-class) you want to use and declare it in the *path operation decorator*.
-
-```Python hl_lines="2 7"
-{!./src/custom_response/tutorial001.py!}
-```
-
-!!! note
-    Notice that you import it directly from `starlette.responses`, not from `fastapi`.
-
-!!! info
-    The parameter `response_class` will also be used to define the "media type" of the response.
-
-    In this case, the HTTP header `Content-Type` will be set to `application/json`.
-
-    And it will be documented as such in OpenAPI.
-
-## HTML Response
-
-To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
-
-* Import `HTMLResponse`.
-* Pass `HTMLResponse` as the parameter `content_type` of your *path operation*.
-
-```Python hl_lines="2 7"
-{!./src/custom_response/tutorial002.py!}
-```
-
-!!! note
-    Notice that you import it directly from `starlette.responses`, not from `fastapi`.
-
-!!! info
-    The parameter `response_class` will also be used to define the "media type" of the response.
-
-    In this case, the HTTP header `Content-Type` will be set to `text/html`.
-
-    And it will be documented as such in OpenAPI.
-
-### Return a Starlette `Response`
-
-As seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}, you can also override the response directly in your *path operation*, by returning it.
-
-The same example from above, returning an `HTMLResponse`, could look like:
-
-```Python hl_lines="2 7 19"
-{!./src/custom_response/tutorial003.py!}
-```
-
-!!! warning
-    A `Response` returned directly by your *path operation function* won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.
-
-!!! info
-    Of course, the actual `Content-Type` header, status code, etc, will come from the `Response` object your returned.
-
-### Document in OpenAPI and override `Response`
-
-If you want to override the response from inside of the function but at the same time document the "media type" in OpenAPI, you can use the `response_class` parameter AND return a `Response` object.
-
-The `response_class` will then be used only to document the OpenAPI *path operation*, but your `Response` will be used as is.
-
-#### Return an `HTMLResponse` directly
-
-For example, it could be something like:
-
-```Python hl_lines="7 23 21"
-{!./src/custom_response/tutorial004.py!}
-```
-
-In this example, the function `generate_html_response()` already generates a Starlette `Response` instead of the HTML in a `str`.
-
-By returning the result of calling `generate_html_response()`, you are already returning a `Response` that will override the default **FastAPI** behavior.
-
-But as you passed the `HTMLResponse` in the `response_class`, **FastAPI** will know how to document it in OpenAPI and the interactive docs as HTML with `text/html`:
-
-<img src="/img/tutorial/custom-response/image01.png">
-
-## Additional documentation
-
-You can also declare the media type and many other details in OpenAPI using `responses`: [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.

docs/contributing.md

@@ -1,175 +0,0 @@
-First, you might want to see the basic ways to [help FastAPI and get help](help-fastapi.md){.internal-link target=_blank}.
-
-## Developing
-
-If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
-
-### Virtual environment with `venv`
-
-You can create a virtual environment in a directory using Python's `venv` module:
-
-```console
-$ python -m venv env
-```
-
-That will create a directory `./env/` with the Python binaries and then you will be able to install packages for that isolated environment.
-
-### Activate the environment
-
-Activate the new environment with:
-
-```console
-$ source ./env/bin/activate
-```
-
-Or in Windows' PowerShell:
-
-```console
-$ .\env\Scripts\Activate.ps1
-```
-
-Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
-
-```console
-$ source ./env/Scripts/activate
-```
-
-To check it worked, use:
-
-```console
-$ which pip
-
-some/directory/fastapi/env/bin/pip
-```
-
-If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
-
-Or in Windows PowerShell:
-
-```console
-$ Get-Command pip
-
-some/directory/fastapi/env/bin/pip
-```
-!!! tip
-    Every time you install a new package with `pip` under that environment, activate the environment again.
-
-    This makes sure that if you use a terminal program installed by that package (like `flit`), you use the one from your local environment and not any other that could be installed globally.
-
-### Flit
-
-**FastAPI** uses <a href="https://flit.readthedocs.io/en/latest/index.html" class="external-link" target="_blank">Flit</a> to build, package and publish the project.
-
-After activating the environment  as described above, install `flit`:
-
-```console
-$ pip install flit
-```
-
-Now re-activate the environment to make sure you are using the `flit` you just installed (and not a global one).
-
-And now use `flit` to install the development dependencies:
-
-```console
-$ flit install --deps develop --symlink
-```
-
-It will install all the dependencies and your local FastAPI in your local environment.
-
-#### Using your local FastAPI
-
-If you create a Python file that imports and uses FastAPI, and run it with the Python from your local environment, it will use your local FastAPI source code.
-
-And if you update that local FastAPI source code, as it is installed with `--symlink`, when you run that Python file again, it will use the fresh version of FastAPI you just edited.
-
-That way, you don't have to "install" your local version to be able to test every change.
-
-### Format
-
-There is a script that you can run that will format and clean all your code:
-
-```console
-$ bash scripts/format.sh
-```
-
-It will also auto-sort all your imports.
-
-For it to sort them correctly, you need to have FastAPI installed locally in your environment, with the command in the section above:
-
-```console
-$ flit install --symlink
-```
-
-### Format imports
-
-There is another script that formats all the imports and makes sure you don't have unused imports:
-
-```console
-$ bash scripts/format-imports.sh
-```
-
-As it runs one command after the other and modifies and reverts many files, it takes a bit longer to run, so it might be easier to use `scripts/format.sh` frequently and `scripts/format-imports.sh` only before committing.
-
-## Docs
-
-The documentation uses <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
-
-All the documentation is in Markdown format in the directory `./docs`.
-
-Many of the tutorials have blocks of code.
-
-In most of the cases, these blocks of code are actual complete applications that can be run as is.
-
-In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs/src/` directory.
-
-And those Python files are included/injected in the documentation when generating the site.
-
-### Docs for tests
-
-Most of the tests actually run against the example source files in the documentation.
-
-This helps making sure that:
-
-* The documentation is up to date.
-* The documentation examples can be run as is.
-* Most of the features are covered by the documentation, ensured by test coverage.
-
-During local development, there is a script that builds the site and checks for any changes, live-reloading:
-
-```console
-$ bash scripts/docs-live.sh
-```
-
-It will serve the documentation on `http://0.0.0.0:8008`.
-
-That way, you can edit the documentation/source files and see the changes live.
-
-### Apps and docs at the same time
-
-If you run the examples with, e.g.:
-
-```console
-$ uvicorn tutorial001:app --reload
-```
-
-as Uvicorn by default will use the port `8000`, the documentation on port `8008` won't clash.
-
-## Tests
-
-There is a script that you can run locally to test all the code and generate coverage reports in HTML:
-
-```console
-$ bash scripts/test-cov-html.sh
-```
-
-This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.
-
-### Tests in your editor
-
-If you want to use the integrated tests in your editor add `./docs/src` to your `PYTHONPATH` variable.
-
-For example, in VS Code you can create a file `.env` with:
-
-```env
-PYTHONPATH=./docs/src
-```

docs/en/docs/advanced/additional-responses.md

@@ -1,3 +1,5 @@
+# Additional Responses in OpenAPI
+
 !!! warning
     This is a rather advanced topic.
 
@@ -22,7 +24,7 @@ Each of those response `dict`s can have a key `model`, containing a Pydantic mod
 For example, to declare another response with a status code `404` and a Pydantic model `Message`, you can write:
 
 ```Python hl_lines="18 23"
-{!./src/additional_responses/tutorial001.py!}
+{!../../../docs_src/additional_responses/tutorial001.py!}
 ```
 
 !!! note
@@ -167,7 +169,7 @@ You can use this same `responses` parameter to add different media types for the
 For example, you can add an additional media type of `image/png`, declaring that your *path operation* can return a JSON object (with media type `application/json`) or a PNG image:
 
 ```Python hl_lines="17 18 19 20 21 22 23 24 28"
-{!./src/additional_responses/tutorial002.py!}
+{!../../../docs_src/additional_responses/tutorial002.py!}
 ```
 
 !!! note
@@ -191,7 +193,7 @@ For example, you can declare a response with a status code `404` that uses a Pyd
 And a response with a status code `200` that uses your `response_model`, but includes a custom `example`:
 
 ```Python hl_lines="20 21 22 23 24 25 26 27 28 29 30 31"
-{!./src/additional_responses/tutorial003.py!}
+{!../../../docs_src/additional_responses/tutorial003.py!}
 ```
 
 It will all be combined and included in your OpenAPI, and shown in the API docs:
@@ -227,7 +229,7 @@ You can use that technique to re-use some predefined responses in your *path ope
 For example:
 
 ```Python hl_lines="11 12 13 14 15 24"
-{!./src/additional_responses/tutorial004.py!}
+{!../../../docs_src/additional_responses/tutorial004.py!}
 ```
 
 ## More information about OpenAPI responses

docs/en/docs/advanced/additional-status-codes.md

@@ -1,4 +1,6 @@
-By default, **FastAPI** will return the responses using Starlette's `JSONResponse`, putting the content you return from your *path operation* inside of that `JSONResponse`.
+# Additional Status Codes
+
+By default, **FastAPI** will return the responses using a `JSONResponse`, putting the content you return from your *path operation* inside of that `JSONResponse`.
 
 It will use the default status code or the one you set in your *path operation*.
 
@@ -12,8 +14,8 @@ But you also want it to accept new items. And when the items didn't exist before
 
 To achieve that, import `JSONResponse`, and return your content there directly, setting the `status_code` that you want:
 
-```Python hl_lines="2 20"
-{!./src/additional_status_codes/tutorial001.py!}
+```Python hl_lines="2  19"
+{!../../../docs_src/additional_status_codes/tutorial001.py!}
 ```
 
 !!! warning
@@ -23,8 +25,13 @@ To achieve that, import `JSONResponse`, and return your content there directly,
     
     Make sure it has the data you want it to have, and that the values are valid JSON (if you are using `JSONResponse`).
 
+!!! note "Technical Details"
+    You could also use `from starlette.responses import JSONResponse`.
+
+    **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `status`.
+
 ## OpenAPI and API docs
 
-If you return additional status codes and responses directly, they won't be included in the OpenAPI schema (the API docs), because FastAPI doesn't have a way to know before hand what you are going to return.
+If you return additional status codes and responses directly, they won't be included in the OpenAPI schema (the API docs), because FastAPI doesn't have a way to know beforehand what you are going to return.
 
 But you can document that in your code, using: [Additional Responses](additional-responses.md){.internal-link target=_blank}.

docs/en/docs/advanced/advanced-dependencies.md

@@ -1,7 +1,4 @@
-!!! warning
-    This is, more or less, an "advanced" chapter.
-    
-    If you are just starting with **FastAPI** you might want to skip this chapter and come back to it later.
+# Advanced Dependencies
 
 ## Parameterized dependencies
 
@@ -22,7 +19,7 @@ Not the class itself (which is already a callable), but an instance of that clas
 To do that, we declare a method `__call__`:
 
 ```Python hl_lines="10"
-{!./src/dependencies/tutorial011.py!}
+{!../../../docs_src/dependencies/tutorial011.py!}
 ```
 
 In this case, this `__call__` is what **FastAPI** will use to check for additional parameters and sub-dependencies, and this is what will be called to pass a value to the parameter in your *path operation function* later.
@@ -32,7 +29,7 @@ In this case, this `__call__` is what **FastAPI** will use to check for addition
 And now, we can use `__init__` to declare the parameters of the instance that we can use to "parameterize" the dependency:
 
 ```Python hl_lines="7"
-{!./src/dependencies/tutorial011.py!}
+{!../../../docs_src/dependencies/tutorial011.py!}
 ```
 
 In this case, **FastAPI** won't ever touch or care about `__init__`, we will use it directly in our code.
@@ -42,7 +39,7 @@ In this case, **FastAPI** won't ever touch or care about `__init__`, we will use
 We could create an instance of this class with:
 
 ```Python hl_lines="16"
-{!./src/dependencies/tutorial011.py!}
+{!../../../docs_src/dependencies/tutorial011.py!}
 ```
 
 And that way we are able to "parameterize" our dependency, that now has `"bar"` inside of it, as the attribute `checker.fixed_content`.
@@ -60,7 +57,7 @@ checker(q="somequery")
 ...and pass whatever that returns as the value of the dependency in our *path operation function* as the parameter `fixed_content_included`:
 
 ```Python hl_lines="20"
-{!./src/dependencies/tutorial011.py!}
+{!../../../docs_src/dependencies/tutorial011.py!}
 ```
 
 !!! tip

docs/en/docs/advanced/async-sql-databases.md

@@ -1,3 +1,5 @@
+# Async SQL (Relational) Databases
+
 You can also use <a href="https://github.com/encode/databases" class="external-link" target="_blank">`encode/databases`</a> with **FastAPI** to connect to databases using `async` and `await`.
 
 It is compatible with:
@@ -22,7 +24,7 @@ Later, for your production application, you might want to use a database server
 * Create a table `notes` using the `metadata` object.
 
 ```Python hl_lines="4 14 16 17 18 19 20 21 22"
-{!./src/async_sql_databases/tutorial001.py!}
+{!../../../docs_src/async_sql_databases/tutorial001.py!}
 ```
 
 !!! tip
@@ -37,7 +39,7 @@ Later, for your production application, you might want to use a database server
 * Create a `database` object.
 
 ```Python hl_lines="3 9 12"
-{!./src/async_sql_databases/tutorial001.py!}
+{!../../../docs_src/async_sql_databases/tutorial001.py!}
 ```
 
 !!! tip
@@ -53,7 +55,7 @@ Here, this section would run directly, right before starting your **FastAPI** ap
 * Create all the tables from the `metadata` object.
 
 ```Python hl_lines="25 26 27 28"
-{!./src/async_sql_databases/tutorial001.py!}
+{!../../../docs_src/async_sql_databases/tutorial001.py!}
 ```
 
 ## Create models
@@ -64,7 +66,7 @@ Create Pydantic models for:
 * Notes to be returned (`Note`).
 
 ```Python hl_lines="31 32 33 36 37 38 39"
-{!./src/async_sql_databases/tutorial001.py!}
+{!../../../docs_src/async_sql_databases/tutorial001.py!}
 ```
 
 By creating these Pydantic models, the input data will be validated, serialized (converted), and annotated (documented).
@@ -77,7 +79,7 @@ So, you will be able to see it all in the interactive API docs.
 * Create event handlers to connect and disconnect from the database.
 
 ```Python hl_lines="42 45 46 47 50 51 52"
-{!./src/async_sql_databases/tutorial001.py!}
+{!../../../docs_src/async_sql_databases/tutorial001.py!}
 ```
 
 ## Read notes
@@ -85,7 +87,7 @@ So, you will be able to see it all in the interactive API docs.
 Create the *path operation function* to read notes:
 
 ```Python hl_lines="55 56 57 58"
-{!./src/async_sql_databases/tutorial001.py!}
+{!../../../docs_src/async_sql_databases/tutorial001.py!}
 ```
 
 !!! Note
@@ -102,7 +104,7 @@ That documents (and validates, serializes, filters) the output data, as a `list`
 Create the *path operation function* to create notes:
 
 ```Python hl_lines="61 62 63 64 65"
-{!./src/async_sql_databases/tutorial001.py!}
+{!../../../docs_src/async_sql_databases/tutorial001.py!}
 ```
 
 !!! Note

docs/en/docs/advanced/custom-request-and-route.md

@@ -1,3 +1,5 @@
+# Custom Request and APIRoute class
+
 In some cases, you may want to override the logic used by the `Request` and `APIRoute` classes.
 
 In particular, this may be a good alternative to logic in a middleware.
@@ -25,14 +27,17 @@ And an `APIRoute` subclass to use that custom request class.
 
 ### Create a custom `GzipRequest` class
 
+!!! tip
+    This is a toy example to demonstrate how it works, if you need Gzip support, you can use the provided [`GzipMiddleware`](./middleware.md#gzipmiddleware){.internal-link target=_blank}.
+
 First, we create a `GzipRequest` class, which will overwrite the `Request.body()` method to decompress the body in the presence of an appropriate header.
 
 If there's no `gzip` in the header, it will not try to decompress the body.
 
 That way, the same route class can handle gzip compressed or uncompressed requests.
 
-```Python hl_lines="10 11 12 13 14 15 16 17"
-{!./src/custom_request_and_route/tutorial001.py!}
+```Python hl_lines="8 9 10 11 12 13 14 15"
+{!../../../docs_src/custom_request_and_route/tutorial001.py!}
 ```
 
 ### Create a custom `GzipRoute` class
@@ -45,8 +50,8 @@ This method returns a function. And that function is what will receive a request
 
 Here we use it to create a `GzipRequest` from the original request.
 
-```Python hl_lines="20 21 22 23 24 25 26 27 28"
-{!./src/custom_request_and_route/tutorial001.py!}
+```Python hl_lines="18 19 20 21 22 23 24 25 26"
+{!../../../docs_src/custom_request_and_route/tutorial001.py!}
 ```
 
 !!! note "Technical Details"
@@ -79,26 +84,26 @@ We can also use this same approach to access the request body in an exception ha
 
 All we need to do is handle the request inside a `try`/`except` block:
 
-```Python hl_lines="15 17"
-{!./src/custom_request_and_route/tutorial002.py!}
+```Python hl_lines="13 15"
+{!../../../docs_src/custom_request_and_route/tutorial002.py!}
 ```
 
 If an exception occurs, the`Request` instance will still be in scope, so we can read and make use of the request body when handling the error:
 
-```Python hl_lines="18 19 20"
-{!./src/custom_request_and_route/tutorial002.py!}
+```Python hl_lines="16 17 18"
+{!../../../docs_src/custom_request_and_route/tutorial002.py!}
 ```
 
 ## Custom `APIRoute` class in a router
 
 You can also set the `route_class` parameter of an `APIRouter`:
 
-```Python hl_lines="28"
-{!./src/custom_request_and_route/tutorial003.py!}
+```Python hl_lines="26"
+{!../../../docs_src/custom_request_and_route/tutorial003.py!}
 ```
 
 In this example, the *path operations* under the `router` will use the custom `TimedRoute` class, and will have an extra `X-Response-Time` header in the response with the time it took to generate the response:
 
-```Python hl_lines="15 16 17 18 19 20 21 22"
-{!./src/custom_request_and_route/tutorial003.py!}
+```Python hl_lines="13 14 15 16 17 18 19 20"
+{!../../../docs_src/custom_request_and_route/tutorial003.py!}
 ```

docs/en/docs/advanced/custom-response.md

@@ -0,0 +1,208 @@
+# Custom Response - HTML, Stream, File, others
+
+By default, **FastAPI** will return the responses using `JSONResponse`.
+
+You can override it by returning a `Response` directly as seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}.
+
+But if you return a `Response` directly, the data won't be automatically converted, and the documentation won't be automatically generated (for example, including the specific "media type", in the HTTP header `Content-Type` as part of the generated OpenAPI).
+
+But you can also declare the `Response` that you want to be used, in the *path operation decorator*.
+
+The contents that you return from your *path operation function* will be put inside of that `Response`.
+
+And if that `Response` has a JSON media type (`application/json`), like is the case with the `JSONResponse` and `UJSONResponse`, the data you return will be automatically converted (and filtered) with any Pydantic `response_model` that you declared in the *path operation decorator*.
+
+!!! note
+    If you use a response class with no media type, FastAPI will expect your response to have no content, so it will not document the response format in its generated OpenAPI docs.
+
+## Use `ORJSONResponse`
+
+For example, if you are squeezing performance, you can install and use <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a> and set the response to be `ORJSONResponse`.
+
+Import the `Response` class (sub-class) you want to use and declare it in the *path operation decorator*.
+
+```Python hl_lines="2 7"
+{!../../../docs_src/custom_response/tutorial001b.py!}
+```
+
+!!! info
+    The parameter `response_class` will also be used to define the "media type" of the response.
+
+    In this case, the HTTP header `Content-Type` will be set to `application/json`.
+
+    And it will be documented as such in OpenAPI.
+
+!!! tip
+    The `ORJSONResponse` is currently only available in FastAPI, not in Starlette.
+
+## HTML Response
+
+To return a response with HTML directly from **FastAPI**, use `HTMLResponse`.
+
+* Import `HTMLResponse`.
+* Pass `HTMLResponse` as the parameter `content_type` of your *path operation*.
+
+```Python hl_lines="2 7"
+{!../../../docs_src/custom_response/tutorial002.py!}
+```
+
+!!! info
+    The parameter `response_class` will also be used to define the "media type" of the response.
+
+    In this case, the HTTP header `Content-Type` will be set to `text/html`.
+
+    And it will be documented as such in OpenAPI.
+
+### Return a `Response`
+
+As seen in [Return a Response directly](response-directly.md){.internal-link target=_blank}, you can also override the response directly in your *path operation*, by returning it.
+
+The same example from above, returning an `HTMLResponse`, could look like:
+
+```Python hl_lines="2 7 19"
+{!../../../docs_src/custom_response/tutorial003.py!}
+```
+
+!!! warning
+    A `Response` returned directly by your *path operation function* won't be documented in OpenAPI (for example, the `Content-Type` won't be documented) and won't be visible in the automatic interactive docs.
+
+!!! info
+    Of course, the actual `Content-Type` header, status code, etc, will come from the `Response` object your returned.
+
+### Document in OpenAPI and override `Response`
+
+If you want to override the response from inside of the function but at the same time document the "media type" in OpenAPI, you can use the `response_class` parameter AND return a `Response` object.
+
+The `response_class` will then be used only to document the OpenAPI *path operation*, but your `Response` will be used as is.
+
+#### Return an `HTMLResponse` directly
+
+For example, it could be something like:
+
+```Python hl_lines="7 23 21"
+{!../../../docs_src/custom_response/tutorial004.py!}
+```
+
+In this example, the function `generate_html_response()` already generates and returns a `Response` instead of returning the HTML in a `str`.
+
+By returning the result of calling `generate_html_response()`, you are already returning a `Response` that will override the default **FastAPI** behavior.
+
+But as you passed the `HTMLResponse` in the `response_class` too, **FastAPI** will know how to document it in OpenAPI and the interactive docs as HTML with `text/html`:
+
+<img src="/img/tutorial/custom-response/image01.png">
+
+## Available responses
+
+Here are some of the available responses.
+
+Have in mind that you can use `Response` to return anything else, or even create a custom sub-class.
+
+!!! note "Technical Details"
+    You could also use `from starlette.responses import HTMLResponse`.
+
+    **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+### `Response`
+
+The main `Response` class, all the other responses inherit from it.
+
+You can return it directly.
+
+It accepts the following parameters:
+
+* `content` - A `str` or `bytes`.
+* `status_code` - An `int` HTTP status code.
+* `headers` - A `dict` of strings.
+* `media_type` - A `str` giving the media type. E.g. `"text/html"`.
+
+FastAPI (actually Starlette) will automatically include a Content-Length header. It will also include a Content-Type header, based on the media_type and appending a charset for text types.
+
+```Python hl_lines="1  18"
+{!../../../docs_src/response_directly/tutorial002.py!}
+```
+
+### `HTMLResponse`
+
+Takes some text or bytes and returns an HTML response, as you read above.
+
+### `PlainTextResponse`
+
+Takes some text or bytes and returns an plain text response.
+
+```Python hl_lines="2  7  9"
+{!../../../docs_src/custom_response/tutorial005.py!}
+```
+
+### `JSONResponse`
+
+Takes some data and returns an `application/json` encoded response.
+
+This is the default response used in **FastAPI**, as you read above.
+
+### `ORJSONResponse`
+
+A fast alternative JSON response using <a href="https://github.com/ijl/orjson" class="external-link" target="_blank">`orjson`</a>, as you read above.
+
+### `UJSONResponse`
+
+An alternative JSON response using <a href="https://github.com/ultrajson/ultrajson" class="external-link" target="_blank">`ujson`</a>.
+
+!!! warning
+    `ujson` is less careful than Python's built-in implementation in how it handles some edge-cases.
+
+```Python hl_lines="2 7"
+{!../../../docs_src/custom_response/tutorial001.py!}
+```
+
+!!! tip
+    It's possible that `ORJSONResponse` might be a faster alternative.
+
+### `RedirectResponse`
+
+Returns an HTTP redirect. Uses a 307 status code (Temporary Redirect) by default.
+
+```Python hl_lines="2  9"
+{!../../../docs_src/custom_response/tutorial006.py!}
+```
+
+### `StreamingResponse`
+
+Takes an async generator or a normal generator/iterator and streams the response body.
+
+```Python hl_lines="2  14"
+{!../../../docs_src/custom_response/tutorial007.py!}
+```
+
+#### Using `StreamingResponse` with file-like objects
+
+If you have a file-like object (e.g. the object returned by `open()`), you can return it in a `StreamingResponse`.
+
+This includes many libraries to interact with cloud storage, video processing, and others.
+
+```Python hl_lines="2  10 11"
+{!../../../docs_src/custom_response/tutorial008.py!}
+```
+
+!!! tip
+    Notice that here as we are using standard `open()` that doesn't support `async` and `await`, we declare the path operation with normal `def`.
+
+### `FileResponse`
+
+Asynchronously streams a file as the response.
+
+Takes a different set of arguments to instantiate than the other response types:
+
+* `path` - The filepath to the file to stream.
+* `headers` - Any custom headers to include, as a dictionary.
+* `media_type` - A string giving the media type. If unset, the filename or path will be used to infer a media type.
+* `filename` - If set, this will be included in the response `Content-Disposition`.
+
+File responses will include appropriate `Content-Length`, `Last-Modified` and `ETag` headers.
+
+```Python hl_lines="2  10"
+{!../../../docs_src/custom_response/tutorial009.py!}
+```
+
+## Additional documentation
+
+You can also declare the media type and many other details in OpenAPI using `responses`: [Additional Responses in OpenAPI](additional-responses.md){.internal-link target=_blank}.

docs/en/docs/advanced/events.md

@@ -1,3 +1,4 @@
+# Events: startup - shutdown
 
 You can define event handlers (functions) that need to be executed before the application starts up, or when the application is shutting down.
 
@@ -8,7 +9,7 @@ These functions can be declared with `async def` or normal `def`.
 To add a function that should be run before the application starts, declare it with the event `"startup"`:
 
 ```Python hl_lines="8"
-{!./src/events/tutorial001.py!}
+{!../../../docs_src/events/tutorial001.py!}
 ```
 
 In this case, the `startup` event handler function will initialize the items "database" (just a `dict`) with some values.
@@ -22,7 +23,7 @@ And your application won't start receiving requests until all the `startup` even
 To add a function that should be run when the application is shutting down, declare it with the event `"shutdown"`:
 
 ```Python hl_lines="6"
-{!./src/events/tutorial002.py!}
+{!../../../docs_src/events/tutorial002.py!}
 ```
 
 Here, the `shutdown` event handler function will write a text line `"Application shutdown"` to a file `log.txt`.

docs/en/docs/advanced/extending-openapi.md

@@ -1,3 +1,5 @@
+# Extending OpenAPI
+
 !!! warning
     This is a rather advanced feature. You probably can skip it.
 
@@ -43,7 +45,7 @@ For example, let's add <a href="https://github.com/Rebilly/ReDoc/blob/master/doc
 First, write all your **FastAPI** application as normally:
 
 ```Python hl_lines="1 4 7 8 9"
-{!./src/extending_openapi/tutorial001.py!}
+{!../../../docs_src/extending_openapi/tutorial001.py!}
 ```
 
 ### Generate the OpenAPI schema
@@ -51,7 +53,7 @@ First, write all your **FastAPI** application as normally:
 Then, use the same utility function to generate the OpenAPI schema, inside a `custom_openapi()` function:
 
 ```Python hl_lines="2 15 16 17 18 19 20"
-{!./src/extending_openapi/tutorial001.py!}
+{!../../../docs_src/extending_openapi/tutorial001.py!}
 ```
 
 ### Modify the OpenAPI schema
@@ -59,7 +61,7 @@ Then, use the same utility function to generate the OpenAPI schema, inside a `cu
 Now you can add the ReDoc extension, adding a custom `x-logo` to the `info` "object" in the OpenAPI schema:
 
 ```Python hl_lines="21 22 23"
-{!./src/extending_openapi/tutorial001.py!}
+{!../../../docs_src/extending_openapi/tutorial001.py!}
 ```
 
 ### Cache the OpenAPI schema
@@ -71,7 +73,7 @@ That way, your application won't have to generate the schema every time a user o
 It will be generated only once, and then the same cached schema will be used for the next requests.
 
 ```Python hl_lines="13 14 24 25"
-{!./src/extending_openapi/tutorial001.py!}
+{!../../../docs_src/extending_openapi/tutorial001.py!}
 ```
 
 ### Override the method
@@ -79,7 +81,7 @@ It will be generated only once, and then the same cached schema will be used for
 Now you can replace the `.openapi()` method with your new function.
 
 ```Python hl_lines="28"
-{!./src/extending_openapi/tutorial001.py!}
+{!../../../docs_src/extending_openapi/tutorial001.py!}
 ```
 
 ### Check it
@@ -155,17 +157,24 @@ After that, your file structure could look like:
 
 Now you need to install `aiofiles`:
 
-```bash
-pip install aiofiles
+
+<div class="termy">
+
+```console
+$ pip install aiofiles
+
+---> 100%
 ```
 
+</div>
+
 ### Serve the static files
 
-* Import `StaticFiles` from Starlette.
+* Import `StaticFiles`.
 * "Mount" a `StaticFiles()` instance in a specific path.
 
 ```Python hl_lines="7 11"
-{!./src/extending_openapi/tutorial002.py!}
+{!../../../docs_src/extending_openapi/tutorial002.py!}
 ```
 
 ### Test the static files
@@ -199,7 +208,7 @@ The first step is to disable the automatic docs, as those use the CDN by default
 To disable them, set their URLs to `None` when creating your `FastAPI` app:
 
 ```Python hl_lines="9"
-{!./src/extending_openapi/tutorial002.py!}
+{!../../../docs_src/extending_openapi/tutorial002.py!}
 ```
 
 ### Include the custom docs
@@ -217,7 +226,7 @@ You can re-use FastAPI's internal functions to create the HTML pages for the doc
 And similarly for ReDoc...
 
 ```Python hl_lines="2 3 4 5 6   14 15 16 17 18 19 20 21 22    25 26 27   30 31 32 33 34 35 36"
-{!./src/extending_openapi/tutorial002.py!}
+{!../../../docs_src/extending_openapi/tutorial002.py!}
 ```
 
 !!! tip
@@ -232,7 +241,7 @@ And similarly for ReDoc...
 Now, to be able to test that everything works, create a *path operation*:
 
 ```Python hl_lines="39 40 41"
-{!./src/extending_openapi/tutorial002.py!}
+{!../../../docs_src/extending_openapi/tutorial002.py!}
 ```
 
 ### Test it

docs/en/docs/advanced/graphql.md

@@ -1,3 +1,4 @@
+# GraphQL
 
 **FastAPI** has optional support for GraphQL (provided by Starlette directly), using the `graphene` library.
 
@@ -10,7 +11,7 @@ GraphQL is implemented with Graphene, you can check <a href="https://docs.graphe
 Import `graphene` and define your GraphQL data:
 
 ```Python hl_lines="1 6 7 8 9 10"
-{!./src/graphql/tutorial001.py!}
+{!../../../docs_src/graphql/tutorial001.py!}
 ```
 
 ## Add Starlette's `GraphQLApp`
@@ -18,7 +19,7 @@ Import `graphene` and define your GraphQL data:
 Then import and add Starlette's `GraphQLApp`:
 
 ```Python hl_lines="3 14"
-{!./src/graphql/tutorial001.py!}
+{!../../../docs_src/graphql/tutorial001.py!}
 ```
 
 !!! info

docs/en/docs/advanced/index.md

@@ -1,3 +1,5 @@
+# Advanced User Guide - Intro
+
 ## Additional Features
 
 The main [Tutorial - User Guide](../tutorial/){.internal-link target=_blank} should be enough to give you a tour through all the main features of **FastAPI**.

docs/en/docs/advanced/middleware.md

@@ -0,0 +1,99 @@
+# Advanced Middleware
+
+In the main tutorial you read how to add [Custom Middleware](../tutorial/middleware.md){.internal-link target=_blank} to your application.
+
+And then you also read how to handle [CORS with the `CORSMiddleware`](../tutorial/cors.md){.internal-link target=_blank}.
+
+In this section we'll see how to use other middlewares.
+
+## Adding ASGI middlewares
+
+As **FastAPI** is based on Starlette and implements the <abbr title="Asynchronous Server Gateway Interface">ASGI</abbr> specification, you can use any ASGI middleware.
+
+A middleware doesn't have to be made for FastAPI or Starlette to work, as long as it follows the ASGI spec.
+
+In general, ASGI middlewares are classes that expect to receive an ASGI app as the first argument.
+
+So, in the documentation for third-party ASGI middlewares they will probably tell you to do something like:
+
+```Python
+from unicorn import UnicornMiddleware
+
+app = SomeASGIApp()
+
+new_app = UnicornMiddleware(app, some_config="rainbow")
+```
+
+But FastAPI (actually Starlette) provides a simpler way to do it that makes sure that the internal middlewares to handle server errors and custom exception handlers work properly.
+
+For that, you use `app.add_middleware()` (as in the example for CORS).
+
+```Python
+from fastapi import FastAPI
+from unicorn import UnicornMiddleware
+
+app = FastAPI()
+
+app.add_middleware(UnicornMiddleware, some_config="rainbow")
+```
+
+`app.add_middleware()` receives a middleware class as the first argument and any additional arguments to be passed to the middleware.
+
+## Integrated middlewares
+
+**FastAPI** includes several middlewares for common use cases, we'll see next how to use them.
+
+!!! note "Technical Details"
+    For the next examples, you could also use `from starlette.middleware.something import SomethingMiddleware`.
+
+    **FastAPI** provides several middlewares in `fastapi.middleware` just as a convenience for you, the developer. But most of the available middlewares come directly from Starlette.
+
+## `HTTPSRedirectMiddleware`
+
+Enforces that all incoming requests must either be `https` or `wss`.
+
+Any incoming requests to `http` or `ws` will be redirected to the secure scheme instead.
+
+```Python hl_lines="2  6"
+{!../../../docs_src/advanced_middleware/tutorial001.py!}
+```
+
+## `TrustedHostMiddleware`
+
+Enforces that all incoming requests have a correctly set `Host` header, in order to guard against HTTP Host Header attacks.
+
+```Python hl_lines="2  6 7 8"
+{!../../../docs_src/advanced_middleware/tutorial002.py!}
+```
+
+The following arguments are supported:
+
+* `allowed_hosts` - A list of domain names that should be allowed as hostnames. Wildcard domains such as `*.example.com` are supported for matching subdomains to allow any hostname either use `allowed_hosts=["*"]` or omit the middleware.
+
+If an incoming request does not validate correctly then a `400` response will be sent.
+
+## `GZipMiddleware`
+
+Handles GZip responses for any request that includes `"gzip"` in the `Accept-Encoding` header.
+
+The middleware will handle both standard and streaming responses.
+
+```Python hl_lines="2  6"
+{!../../../docs_src/advanced_middleware/tutorial003.py!}
+```
+
+The following arguments are supported:
+
+* `minimum_size` - Do not GZip responses that are smaller than this minimum size in bytes. Defaults to `500`.
+
+## Other middlewares
+
+There are many other ASGI middlewares.
+
+For example:
+
+* <a href="https://docs.sentry.io/platforms/python/asgi/" class="external-link" target="_blank">Sentry</a>
+* <a href="https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py" class="external-link" target="_blank">Uvicorn's `ProxyHeadersMiddleware`</a>
+* <a href="https://github.com/florimondmanca/msgpack-asgi" class="external-link" target="_blank">MessagePack</a>
+
+To see other available middlewares check <a href="https://www.starlette.io/middleware/" class="external-link" target="_blank">Starlette's Middleware docs</a> and the <a href="https://github.com/florimondmanca/awesome-asgi" class="external-link" target="_blank">ASGI Awesome List</a>.

docs/en/docs/advanced/nosql-databases.md

@@ -1,3 +1,5 @@
+# NoSQL (Distributed / Big Data) Databases
+
 **FastAPI** can also be integrated with any <abbr title="Distributed database (Big Data), also 'Not Only SQL'">NoSQL</abbr>.
 
 Here we'll see an example using **<a href="https://www.couchbase.com/" class="external-link" target="_blank">Couchbase</a>**, a <abbr title="Document here refers to a JSON object (a dict), with keys and values, and those values can also be other JSON objects, arrays (lists), numbers, strings, booleans, etc.">document</abbr> based NoSQL database.
@@ -18,7 +20,7 @@ You can adapt it to any other NoSQL database like:
 For now, don't pay attention to the rest, only the imports:
 
 ```Python hl_lines="6 7 8"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 ## Define a constant to use as a "document type"
@@ -28,7 +30,7 @@ We will use it later as a fixed field `type` in our documents.
 This is not required by Couchbase, but is a good practice that will help you afterwards.
 
 ```Python hl_lines="10"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 ## Add a function to get a `Bucket`
@@ -53,7 +55,7 @@ This utility function will:
 * Return it.
 
 ```Python hl_lines="13 14 15 16 17 18 19 20 21 22"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 ## Create Pydantic models
@@ -65,7 +67,7 @@ As **Couchbase** "documents" are actually just "JSON objects", we can model them
 First, let's create a `User` model:
 
 ```Python hl_lines="25 26 27 28 29"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 We will use this model in our *path operation function*, so, we don't include in it the `hashed_password`.
@@ -79,7 +81,7 @@ This will have the data that is actually stored in the database.
 We don't create it as a subclass of Pydantic's `BaseModel` but as a subclass of our own `User`, because it will have all the attributes in `User` plus a couple more:
 
 ```Python hl_lines="32 33 34"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 !!! note
@@ -99,7 +101,7 @@ Now create a function that will:
 By creating a function that is only dedicated to getting your user from a `username` (or any other parameter) independent of your *path operation function*, you can more easily re-use it in multiple parts and also add <abbr title="Automated test, written in code, that checks if another piece of code is working correctly.">unit tests</abbr> for it:
 
 ```Python hl_lines="37 38 39 40 41 42 43"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 ### f-strings
@@ -134,7 +136,7 @@ UserInDB(username="johndoe", hashed_password="some_hash")
 ### Create the `FastAPI` app
 
 ```Python hl_lines="47"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 ### Create the *path operation function*
@@ -144,7 +146,7 @@ As our code is calling Couchbase and we are not using the <a href="https://docs.
 Also, Couchbase recommends not using a single `Bucket` object in multiple "<abbr title="A sequence of code being executed by the program, while at the same time, or at intervals, there can be others being executed too.">thread</abbr>s", so, we can get just get the bucket directly and pass it to our utility functions:
 
 ```Python hl_lines="50 51 52 53 54"
-{!./src/nosql_databases/tutorial001.py!}
+{!../../../docs_src/nosql_databases/tutorial001.py!}
 ```
 
 ## Recap

docs/en/docs/advanced/openapi-callbacks.md

@@ -1,3 +1,5 @@
+# OpenAPI Callbacks
+
 You could create an API with a *path operation* that could trigger a request to an *external API* created by someone else (probably the same developer that would be *using* your API).
 
 The process that happens when your API app calls the *external API* is named a "callback". Because the software that the external developer wrote sends a request to your API and then your API *calls back*, sending a request to an *external API* (that was probably created by the same developer).
@@ -30,7 +32,7 @@ It will have a *path operation* that will receive an `Invoice` body, and a query
 This part is pretty normal, most of the code is probably already familiar to you:
 
 ```Python hl_lines="8 9 10 11 12  34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53"
-{!./src/openapi_callbacks/tutorial001.py!}
+{!../../../docs_src/openapi_callbacks/tutorial001.py!}
 ```
 
 !!! tip
@@ -91,7 +93,7 @@ Because of that, you need to declare what will be the `default_response_class`,
     But as we are never calling `app.include_router(some_router)`, we need to set the `default_response_class` during creation of the `APIRouter`.
 
 ```Python hl_lines="3 24"
-{!./src/openapi_callbacks/tutorial001.py!}
+{!../../../docs_src/openapi_callbacks/tutorial001.py!}
 ```
 
 ### Create the callback *path operation*
@@ -104,7 +106,7 @@ It should look just like a normal FastAPI *path operation*:
 * And it could also have a declaration of the response it should return, e.g. `response_model=InvoiceEventReceived`.
 
 ```Python hl_lines="15 16 17  20 21  27 28 29 30 31"
-{!./src/openapi_callbacks/tutorial001.py!}
+{!../../../docs_src/openapi_callbacks/tutorial001.py!}
 ```
 
 There are 2 main differences from a normal *path operation*:
@@ -171,7 +173,7 @@ At this point you have the *callback path operation(s)* needed (the one(s) that
 Now use the parameter `callbacks` in *your API's path operation decorator* to pass the attribute `.routes` (that's actually just a `list` of routes/*path operations*) from that callback router:
 
 ```Python hl_lines="34"
-{!./src/openapi_callbacks/tutorial001.py!}
+{!../../../docs_src/openapi_callbacks/tutorial001.py!}
 ```
 
 !!! tip

docs/en/docs/advanced/path-operation-advanced-configuration.md

@@ -1,3 +1,5 @@
+# Path Operation Advanced Configuration
+
 ## OpenAPI operationId
 
 !!! warning
@@ -8,7 +10,7 @@ You can set the OpenAPI `operationId` to be used in your *path operation* with t
 You would have to make sure that it is unique for each operation.
 
 ```Python hl_lines="6"
-{!./src/path_operation_advanced_configuration/tutorial001.py!}
+{!../../../docs_src/path_operation_advanced_configuration/tutorial001.py!}
 ```
 
 ### Using the *path operation function* name as the operationId
@@ -18,7 +20,7 @@ If you want to use your APIs' function names as `operationId`s, you can iterate
 You should do it after adding all your *path operations*.
 
 ```Python hl_lines="2 12 13 14 15 16 17 18 19 20 21 24"
-{!./src/path_operation_advanced_configuration/tutorial002.py!}
+{!../../../docs_src/path_operation_advanced_configuration/tutorial002.py!}
 ```
 
 !!! tip
@@ -34,7 +36,7 @@ You should do it after adding all your *path operations*.
 To exclude a *path operation* from the generated OpenAPI schema (and thus, from the automatic documentation systems), use the parameter `include_in_schema` and set it to `False`;
 
 ```Python hl_lines="6"
-{!./src/path_operation_advanced_configuration/tutorial003.py!}
+{!../../../docs_src/path_operation_advanced_configuration/tutorial003.py!}
 ```
 
 ## Advanced description from docstring
@@ -46,5 +48,5 @@ Adding an `\f` (an escaped "form feed" character) causes **FastAPI** to truncate
 It won't show up in the documentation, but other tools (such as Sphinx) will be able to use the rest.
 
 ```Python hl_lines="19 20 21 22 23 24 25 26 27 28 29"
-{!./src/path_operation_advanced_configuration/tutorial004.py!}
+{!../../../docs_src/path_operation_advanced_configuration/tutorial004.py!}
 ```

docs/en/docs/advanced/response-change-status-code.md

@@ -1,3 +1,5 @@
+# Response - Change Status Code
+
 You probably read before that you can set a default [Response Status Code](../tutorial/response-status-code.md){.internal-link target=_blank}.
 
 But in some cases you need to return a different status code than the default.
@@ -18,8 +20,8 @@ You can declare a parameter of type `Response` in your *path operation function*
 
 And then you can set the `status_code` in that *temporal* response object.
 
-```Python hl_lines="2 11 14"
-{!./src/response_change_status_code/tutorial001.py!}
+```Python hl_lines="1  9  12"
+{!../../../docs_src/response_change_status_code/tutorial001.py!}
 ```
 
 And then you can return any object you need, as you normally would (a `dict`, a database model, etc).

docs/en/docs/advanced/response-cookies.md

@@ -1,11 +1,13 @@
+# Response Cookies
+
 ## Use a `Response` parameter
 
 You can declare a parameter of type `Response` in your *path operation function*.
 
-And then you can set headers in that *temporal* response object.
+And then you can set cookies in that *temporal* response object.
 
-```Python hl_lines="2 8 9"
-{!./src/response_cookies/tutorial002.py!}
+```Python hl_lines="1  8 9"
+{!../../../docs_src/response_cookies/tutorial002.py!}
 ```
 
 And then you can return any object you need, as you normally would (a `dict`, a database model, etc).
@@ -25,7 +27,7 @@ To do that, you can create a response as described in [Return a Response Directl
 Then set Cookies in it, and then return it:
 
 ```Python hl_lines="10 11 12"
-{!./src/response_cookies/tutorial001.py!}
+{!../../../docs_src/response_cookies/tutorial001.py!}
 ```
 
 !!! tip
@@ -37,4 +39,11 @@ Then set Cookies in it, and then return it:
 
 ### More info
 
+!!! note "Technical Details"
+    You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
+
+    **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+    And as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.
+
 To see all the available parameters and options, check the <a href="https://www.starlette.io/responses/#set-cookie" class="external-link" target="_blank">documentation in Starlette</a>.

docs/en/docs/advanced/response-directly.md

@@ -1,21 +1,23 @@
+# Return a Response Directly
+
 When you create a **FastAPI** *path operation* you can normally return any data from it: a `dict`, a `list`, a Pydantic model, a database model, etc.
 
 By default, **FastAPI** would automatically convert that return value to JSON using the `jsonable_encoder` explained in [JSON Compatible Encoder](../tutorial/encoder.md){.internal-link target=_blank}.
 
-Then, behind the scenes, it would put that JSON-compatible data (e.g. a `dict`) inside of a Starlette `JSONResponse` that would be used to send the response to the client.
+Then, behind the scenes, it would put that JSON-compatible data (e.g. a `dict`) inside of a `JSONResponse` that would be used to send the response to the client.
 
 But you can return a `JSONResponse` directly from your *path operations*.
 
 It might be useful, for example, to return custom headers or cookies.
 
-## Starlette `Response`
+## Return a `Response`
 
-In fact, you can return any <a href="https://www.starlette.io/responses/" class="external-link" target="_blank">Starlette `Response`</a> or any sub-class of it.
+In fact, you can return any `Response` or any sub-class of it.
 
 !!! tip
     `JSONResponse` itself is a sub-class of `Response`.
 
-And when you return a Starlette `Response`, **FastAPI** will pass it directly.
+And when you return a `Response`, **FastAPI** will pass it directly.
 
 It won't do any data conversion with Pydantic models, it won't convert the contents to any type, etc.
 
@@ -30,11 +32,13 @@ For example, you cannot put a Pydantic model in a `JSONResponse` without first c
 For those cases, you can use the `jsonable_encoder` to convert your data before passing it to a response:
 
 ```Python hl_lines="4 6 20 21"
-{!./src/response_directly/tutorial001.py!}
+{!../../../docs_src/response_directly/tutorial001.py!}
 ```
 
-!!! note
-    Notice that you import it directly from `starlette.responses`, not from `fastapi`.
+!!! note "Technical Details"
+    You could also use `from starlette.responses import JSONResponse`.
+
+    **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
 
 ## Returning a custom `Response`
 
@@ -42,14 +46,12 @@ The example above shows all the parts you need, but it's not very useful yet, as
 
 Now, let's see how you could use that to return a custom response.
 
-Let's say you want to return a response that is not available in the default <a href="https://www.starlette.io/responses/" class="external-link" target="_blank">Starlette `Response`s</a>.
+Let's say that you want to return an <a href="https://en.wikipedia.org/wiki/XML" class="external-link" target="_blank">XML</a> response.
 
-Let's say that you want to return <a href="https://en.wikipedia.org/wiki/XML" class="external-link" target="_blank">XML</a>.
+You could put your XML content in a string, put it in a `Response`, and return it:
 
-You could put your XML content in a string, put it in a Starlette Response, and return it:
-
-```Python hl_lines="2 20"
-{!./src/response_directly/tutorial002.py!}
+```Python hl_lines="1  18"
+{!../../../docs_src/response_directly/tutorial002.py!}
 ```
 
 ## Notes

docs/en/docs/advanced/response-headers.md

@@ -1,11 +1,13 @@
+# Response Headers
+
 ## Use a `Response` parameter
 
 You can declare a parameter of type `Response` in your *path operation function* (as you can do for cookies).
 
 And then you can set headers in that *temporal* response object.
 
-```Python hl_lines="2 8 9"
-{!./src/response_headers/tutorial002.py!}
+```Python hl_lines="1  7 8"
+{!../../../docs_src/response_headers/tutorial002.py!}
 ```
 
 And then you can return any object you need, as you normally would (a `dict`, a database model, etc).
@@ -23,9 +25,16 @@ You can also add headers when you return a `Response` directly.
 Create a response as described in [Return a Response Directly](response-directly.md){.internal-link target=_blank} and pass the headers as an additional parameter:
 
 ```Python hl_lines="10 11 12"
-{!./src/response_headers/tutorial001.py!}
+{!../../../docs_src/response_headers/tutorial001.py!}
 ```
 
+!!! note "Technical Details"
+    You could also use `from starlette.responses import Response` or `from starlette.responses import JSONResponse`.
+
+    **FastAPI** provides the same `starlette.responses` as `fastapi.responses` just as a convenience for you, the developer. But most of the available responses come directly from Starlette.
+
+    And as the `Response` can be used frequently to set headers and cookies, **FastAPI** also provides it at `fastapi.Response`.
+
 ## Custom Headers
 
 Have in mind that custom proprietary headers can be added <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers" class="external-link" target="_blank">using the 'X-' prefix</a>.

docs/en/docs/advanced/security/http-basic-auth.md

@@ -1,3 +1,5 @@
+# HTTP Basic Auth
+
 For the simplest cases, you can use HTTP Basic Auth.
 
 In HTTP Basic Auth, the application expects a header that contains a username and a password.
@@ -19,7 +21,7 @@ Then, when you type that username and password, the browser sends them in the he
     * It contains the `username` and `password` sent.
 
 ```Python hl_lines="2 6 10"
-{!./src/security/tutorial006.py!}
+{!../../../docs_src/security/tutorial006.py!}
 ```
 
 When you try to open the URL for the first time (or click the "Execute" button in the docs) the browser will ask you for your username and password:
@@ -34,8 +36,8 @@ Use a dependency to check if the username and password are correct.
 
 For this, use the Python standard module <a href="https://docs.python.org/3/library/secrets.html" class="external-link" target="_blank">`secrets`</a> to check the username and password:
 
-```Python hl_lines="1  13 14 15"
-{!./src/security/tutorial007.py!}
+```Python hl_lines="1  11 12 13"
+{!../../../docs_src/security/tutorial007.py!}
 ```
 
 This will ensure that `credentials.username` is `"stanleyjobson"`, and that `credentials.password` is `"swordfish"`. This would be similar to:
@@ -100,6 +102,6 @@ That way, using `secrets.compare_digest()` in your application code, it will be
 
 After detecting that the credentials are incorrect, return an `HTTPException` with a status code 401 (the same returned when no credentials are provided) and add the header `WWW-Authenticate` to make the browser show the login prompt again:
 
-```Python hl_lines="16 17 18 19 20"
-{!./src/security/tutorial007.py!}
+```Python hl_lines="15 16 17 18 19"
+{!../../../docs_src/security/tutorial007.py!}
 ```

docs/en/docs/advanced/security/index.md

@@ -1,3 +1,5 @@
+# Advanced Security - Intro
+
 ## Additional Features
 
 There are some extra features to handle security apart from the ones covered in the [Tutorial - User Guide: Security](../../tutorial/security/){.internal-link target=_blank}.

docs/en/docs/advanced/security/oauth2-scopes.md

@@ -1,3 +1,5 @@
+# OAuth2 scopes
+
 You can use OAuth2 scopes directly with **FastAPI**, they are integrated to work seamlessly.
 
 This would allow you to have a more fine-grained permission system, following the OAuth2 standard, integrated into your OpenAPI application (and the API docs).
@@ -54,8 +56,8 @@ They are normally used to declare specific security permissions, for example:
 
 First, let's quickly see the parts that change from the examples in the main **Tutorial - User Guide** for [OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}. Now using OAuth2 scopes:
 
-```Python hl_lines="2 5 9 13 48 66 107 109 110 111 112 113 114 115 116 117 123 124 125 126 130 131 132 133 134 135 136 141 155"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="2  5  9  13  47  65  106  108 109 110 111 112 113 114 115 116  122 123 124 125  129 130 131 132 133 134 135  140  154"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 Now let's review those changes step by step.
@@ -66,8 +68,8 @@ The first change is that now we are declaring the OAuth2 security scheme with tw
 
 The `scopes` parameter receives a `dict` with each scope as a key and the description as the value:
 
-```Python hl_lines="64 65 66 67"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="63 64 65 66"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 Because we are now declaring those scopes, they will show up in the API docs when you log-in/authorize.
@@ -91,8 +93,8 @@ And we return the scopes as part of the JWT token.
 
     But in your application, for security, you should make sure you only add the scopes that the user is actually able to have, or the ones you have predefined.
 
-```Python hl_lines="156"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="155"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 ## Declare scopes in *path operations* and dependencies
@@ -116,8 +118,8 @@ In this case, it requires the scope `me` (it could require more than one scope).
     
     We are doing it here to demonstrate how **FastAPI** handles scopes declared at different levels.
 
-```Python hl_lines="5 141 168"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="5  140  167"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 !!! info "Technical Details"
@@ -141,8 +143,8 @@ We also declare a special parameter of type `SecurityScopes`, imported from `fas
 
 This `SecurityScopes` class is similar to `Request` (`Request` was used to get the request object directly).
 
-```Python hl_lines="9 107"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="9  106"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 ## Use the `scopes`
@@ -157,8 +159,8 @@ We create an `HTTPException` that we can re-use (`raise`) later at several point
 
 In this exception, we include the scopes required (if any) as a string separated by spaces (using `scope_str`). We put that string containing the scopes in in the `WWW-Authenticate` header (this is part of the spec).
 
-```Python hl_lines="107 109 110 111 112 113 114 115 116 117"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="106  108 109 110 111 112 113 114 115 116"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 ## Verify the `username` and data shape
@@ -175,8 +177,8 @@ Instead of, for example, a `dict`, or something else, as it could break the appl
 
 We also verify that we have a user with that username, and if not, we raise that same exception we created before.
 
-```Python hl_lines="48 118 119 120 121 122 123 124 125 126 127 128 129"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="47  117 118 119 120 121 122 123 124 125 126 127 128"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 ## Verify the `scopes`
@@ -185,8 +187,8 @@ We now verify that all the scopes required, by this dependency and all the depen
 
 For this, we use `security_scopes.scopes`, that contains a `list` with all these scopes as `str`.
 
-```Python hl_lines="130 131 132 133 134 135 136"
-{!./src/security/tutorial005.py!}
+```Python hl_lines="129 130 131 132 133 134 135"
+{!../../../docs_src/security/tutorial005.py!}
 ```
 
 ## Dependency tree and scopes

docs/en/docs/advanced/sql-databases-peewee.md

@@ -1,3 +1,5 @@
+# SQL (Relational) Databases with Peewee
+
 !!! warning
     If you are just starting, the tutorial [SQL (Relational) Databases](../tutorial/sql-databases.md){.internal-link target=_blank} that uses SQLAlchemy should be enough.
 
@@ -60,7 +62,7 @@ Let's refer to the file `sql_app/database.py`.
 Let's first check all the normal Peewee code, create a Peewee database:
 
 ```Python hl_lines="3  5  22"
-{!./src/sql_databases_peewee/sql_app/database.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/database.py!}
 ```
 
 !!! tip
@@ -112,7 +114,7 @@ This might seem a bit complex (and it actually is), you don't really need to com
 We will create a `PeeweeConnectionState`:
 
 ```Python hl_lines="10 11 12 13 14 15 16 17 18 19"
-{!./src/sql_databases_peewee/sql_app/database.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/database.py!}
 ```
 
 This class inherits from a special internal class used by Peewee.
@@ -133,7 +135,7 @@ So, we need to do some extra tricks to make it work as if it was just using `thr
 Now, overwrite the `._state` internal attribute in the Peewee database `db` object using the new `PeeweeConnectionState`:
 
 ```Python hl_lines="24"
-{!./src/sql_databases_peewee/sql_app/database.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/database.py!}
 ```
 
 !!! tip
@@ -160,7 +162,7 @@ This is the same you would do if you followed the Peewee tutorial and updated th
 Import `db` from `database` (the file `database.py` from above) and use it here.
 
 ```Python hl_lines="3  6 7 8 9 10 11 12  15 16 17 18 19 20 21"
-{!./src/sql_databases_peewee/sql_app/models.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/models.py!}
 ```
 
 !!! tip
@@ -188,7 +190,7 @@ Now let's check the file `sql_app/schemas.py`.
 Create all the same Pydantic models as in the SQLAlchemy tutorial:
 
 ```Python hl_lines="16 17 18  21 22  25 26 27 28 29 30  34 35  38 39  42 43 44 45 46 47 48"
-{!./src/sql_databases_peewee/sql_app/schemas.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/schemas.py!}
 ```
 
 !!! tip
@@ -213,7 +215,7 @@ But recent versions of Pydantic allow providing a custom class that inherits fro
 We are going to create a custom `PeeweeGetterDict` class and use it in all the same Pydantic *models* / schemas that use `orm_mode`:
 
 ```Python hl_lines="3 8 9 10 11 12 13  31  49"
-{!./src/sql_databases_peewee/sql_app/schemas.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/schemas.py!}
 ```
 
 Here we are checking if the attribute that is being accessed (e.g. `.items` in `some_user.items`) is an instance of `peewee.ModelSelect`.
@@ -234,7 +236,7 @@ Now let's see the file `sql_app/crud.py`.
 Create all the same CRUD utils as in the SQLAlchemy tutorial, all the code is very similar:
 
 ```Python hl_lines="1  4 5  8 9  12 13  16 17 18 19 20  23 24  27 28 29 30"
-{!./src/sql_databases_peewee/sql_app/crud.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/crud.py!}
 ```
 
 There are some differences with the code for the SQLAlchemy tutorial.
@@ -258,7 +260,7 @@ And now in the file `sql_app/main.py` let's integrate and use all the other part
 In a very simplistic way create the database tables:
 
 ```Python hl_lines="9 10 11"
-{!./src/sql_databases_peewee/sql_app/main.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/main.py!}
 ```
 
 ### Create a dependency
@@ -266,7 +268,7 @@ In a very simplistic way create the database tables:
 Create a dependency that will connect the database right at the beginning of a request and disconnect it at the end:
 
 ```Python hl_lines="23 24 25 26 27 28 29"
-{!./src/sql_databases_peewee/sql_app/main.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/main.py!}
 ```
 
 Here we have an empty `yield` because we are actually not using the database object directly.
@@ -280,7 +282,7 @@ And then, in each *path operation function* that needs to access the database we
 But we are not using the value given by this dependency (it actually doesn't give any value, as it has an empty `yield`). So, we don't add it to the *path operation function* but to the *path operation decorator* in the `dependencies` parameter:
 
 ```Python hl_lines="32  40  47  59  65  72"
-{!./src/sql_databases_peewee/sql_app/main.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/main.py!}
 ```
 
 ### Context variable sub-dependency
@@ -290,7 +292,7 @@ For all the `contextvars` parts to work, we need to make sure we have an indepen
 For that, we need to create another `async` dependency `reset_db_state()` that is used as a sub-dependency in `get_db()`. It will set the value for the context variable (with just a default `dict`) that will be used as the database state for the whole request. And then the dependency `get_db()` will store in it the database state (connection, transactions, etc).
 
 ```Python hl_lines="18 19 20"
-{!./src/sql_databases_peewee/sql_app/main.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/main.py!}
 ```
 
 For the **next request**, as we will reset that context variable again in the `async` dependency `reset_db_state()` and then create a new connection in the `get_db()` dependency, that new request will have its own database state (connection, transactions, etc).
@@ -319,7 +321,7 @@ async def reset_db_state():
 Now, finally, here's the standard **FastAPI** *path operations* code.
 
 ```Python hl_lines="32 33 34 35 36 37  40 41 42 43  46 47 48 49 50 51 52 53  56 57 58 59 60 61 62  65 66 67 68  71 72 73 74 75 76 77 78 79"
-{!./src/sql_databases_peewee/sql_app/main.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/main.py!}
 ```
 
 ### About `def` vs `async def`
@@ -369,10 +371,16 @@ async def reset_db_state():
 
 Then run your app with Uvicorn:
 
-```bash
-uvicorn sql_app.main:app --reload
+<div class="termy">
+
+```console
+$ uvicorn sql_app.main:app --reload
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
 ```
 
+</div>
+
 Open your browser at <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>  and create a couple of users.
 
 Then open 10 tabs at <a href="http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get" class="external-link" target="_blank">http://127.0.0.1:8000/docs#/default/read_slow_users_slowusers__get</a> at the same time.
@@ -430,31 +438,31 @@ Repeat the same process with the 10 tabs. This time all of them will wait and yo
 * `sql_app/database.py`:
 
 ```Python
-{!./src/sql_databases_peewee/sql_app/database.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/database.py!}
 ```
 
 * `sql_app/models.py`:
 
 ```Python
-{!./src/sql_databases_peewee/sql_app/models.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/models.py!}
 ```
 
 * `sql_app/schemas.py`:
 
 ```Python
-{!./src/sql_databases_peewee/sql_app/schemas.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/schemas.py!}
 ```
 
 * `sql_app/crud.py`:
 
 ```Python
-{!./src/sql_databases_peewee/sql_app/crud.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/crud.py!}
 ```
 
 * `sql_app/main.py`:
 
 ```Python
-{!./src/sql_databases_peewee/sql_app/main.py!}
+{!../../../docs_src/sql_databases_peewee/sql_app/main.py!}
 ```
 
 ## Technical Details

docs/en/docs/advanced/sub-applications-proxy.md

@@ -1,3 +1,5 @@
+# Sub Applications - Behind a Proxy, Mounts
+
 There are at least two situations where you could need to create your **FastAPI** application using some specific paths.
 
 But then you need to set them up to be served with a path prefix.
@@ -44,7 +46,7 @@ You could want to do this if you have several "independent" applications that yo
 First, create the main, top-level, **FastAPI** application, and its *path operations*:
 
 ```Python hl_lines="3 6 7 8"
-{!./src/sub_applications/tutorial001.py!}
+{!../../../docs_src/sub_applications/tutorial001.py!}
 ```
 
 ### Sub-application
@@ -56,7 +58,7 @@ This sub-application is just another standard FastAPI application, but this is t
 When creating the sub-application, use the parameter `openapi_prefix`. In this case, with a prefix of `/subapi`:
 
 ```Python hl_lines="11 14 15 16"
-{!./src/sub_applications/tutorial001.py!}
+{!../../../docs_src/sub_applications/tutorial001.py!}
 ```
 
 ### Mount the sub-application
@@ -66,17 +68,23 @@ In your top-level application, `app`, mount the sub-application, `subapi`.
 Here you need to make sure you use the same path that you used for the `openapi_prefix`, in this case, `/subapi`:
 
 ```Python hl_lines="11 19"
-{!./src/sub_applications/tutorial001.py!}
+{!../../../docs_src/sub_applications/tutorial001.py!}
 ```
 
 ## Check the automatic API docs
 
 Now, run `uvicorn`, if your file is at `main.py`, it would be:
 
-```bash
-uvicorn main:app --reload
+<div class="termy">
+
+```console
+$ uvicorn main:app --reload
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
 ```
 
+</div>
+
 And open the docs at <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
 
 You will see the automatic API docs for the main app, including only its own paths:

docs/en/docs/advanced/templates.md

@@ -1,43 +1,62 @@
+# Templates
+
 You can use any template engine you want with **FastAPI**.
 
 A common election is Jinja2, the same one used by Flask and other tools.
 
-Starlette has utilities to configure it easily that you can use directly in your **FastAPI** application.
+There are utilities to configure it easily that you can use directly in your **FastAPI** application (provided by Starlette).
 
 ## Install dependencies
 
 Install `jinja2`:
 
-```bash
-pip install jinja2
+<div class="termy">
+
+```console
+$ pip install jinja2
+
+---> 100%
 ```
 
+</div>
+
 If you need to also serve static files (as in this example), install `aiofiles`:
 
-```bash
-pip install aiofiles
+<div class="termy">
+
+```console
+$ pip install aiofiles
+
+---> 100%
 ```
 
+</div>
+
 ## Using `Jinja2Templates`
 
-* Import `Jinja2Templates` form Starlette.
+* Import `Jinja2Templates`.
 * Create a `templates` object that you can re-use later.
 * Declare a `Request` parameter in the *path operation* that will return a template.
 * Use the `templates` you created to render and return a `TemplateResponse`, passing the `request` as one of the key-value pairs in the Jinja2 "context".
 
-```Python hl_lines="4 11 15 16"
-{!./src/templates/tutorial001.py!}
+```Python hl_lines="3  10  14 15"
+{!../../../docs_src/templates/tutorial001.py!}
 ```
 
 !!! note
     Notice that you have to pass the `request` as part of the key-value pairs in the context for Jinja2. So, you also have to declare it in your *path operation*.
 
+!!! note "Technical Details"
+    You could also use `from starlette.templating import Jinja2Templates`.
+
+    **FastAPI** provides the same `starlette.templating` as `fastapi.templating` just as a convenience for you, the developer. But most of the available responses come directly from Starlette. The same with `Request` and `StaticFiles`.
+
 ## Writing templates
 
 Then you can write a template at `templates/item.html` with:
 
 ```jinja hl_lines="7"
-{!./src/templates/templates/item.html!}
+{!../../../docs_src/templates/templates/item.html!}
 ```
 
 It will show the `id` taken from the "context" `dict` you passed:
@@ -51,13 +70,13 @@ It will show the `id` taken from the "context" `dict` you passed:
 And you can also use `url_for()` inside of the template, and use it, for example, with the `StaticFiles` you mounted.
 
 ```jinja hl_lines="4"
-{!./src/templates/templates/item.html!}
+{!../../../docs_src/templates/templates/item.html!}
 ```
 
 In this example, it would link to a CSS file at `static/styles.css` with:
 
 ```CSS hl_lines="4"
-{!./src/templates/static/styles.css!}
+{!../../../docs_src/templates/static/styles.css!}
 ```
 
 And because you are using `StaticFiles`, that CSS file would be served automatically by your **FastAPI** application at the URL `/static/styles.css`.

docs/en/docs/advanced/testing-dependencies.md

@@ -1,3 +1,5 @@
+# Testing Dependencies with Overrides
+
 ## Overriding dependencies during testing
 
 There are some scenarios where you might want to override a dependency during testing.
@@ -39,7 +41,7 @@ To override a dependency for testing, you put as a key the original dependency (
 And then **FastAPI** will call that override instead of the original dependency.
 
 ```Python hl_lines="24 25 28"
-{!./src/dependency_testing/tutorial001.py!}
+{!../../../docs_src/dependency_testing/tutorial001.py!}
 ```
 
 !!! tip

docs/en/docs/advanced/testing-events.md

@@ -1,7 +1,7 @@
-## Testing Events, `startup` and `shutdown`
+# Testing Events: startup - shutdown
 
 When you need your event handlers (`startup` and `shutdown`) to run in your tests, you can use the `TestClient` with a `with` statement:
 
 ```Python hl_lines="9 10 11 12 20 21 22 23 24"
-{!./src/app_testing/tutorial003.py!}
-```
+{!../../../docs_src/app_testing/tutorial003.py!}
+```

docs/en/docs/advanced/testing-websockets.md

@@ -1,9 +1,9 @@
-## Testing WebSockets
+# Testing WebSockets
 
 You can use the same `TestClient` to test WebSockets.
 
 For this, you use the `TestClient` in a `with` statement, connecting to the WebSocket:
 
 ```Python hl_lines="27 28 29 30 31"
-{!./src/app_testing/tutorial002.py!}
+{!../../../docs_src/app_testing/tutorial002.py!}
 ```

docs/en/docs/advanced/using-request-directly.md

@@ -1,3 +1,5 @@
+# Using the Request Directly
+
 Up to now, you have been declaring the parts of the request that you need with their types.
 
 Taking data from:
@@ -15,7 +17,7 @@ But there are situations where you might need to access the `Request` object dir
 
 As **FastAPI** is actually **Starlette** underneath, with a layer of several tools on top, you can use Starlette's <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request`</a> object directly when you need to.
 
-It would also mean that if you get data from the `Request` object directly (for example, read the body) it won't be validated, converted or annotated (with OpenAPI, for the automatic documentation) by FastAPI.
+It would also mean that if you get data from the `Request` object directly (for example, read the body) it won't be validated, converted or documented (with OpenAPI, for the automatic API user interface) by FastAPI.
 
 Although any other parameter declared normally (for example, the body with a Pydantic model) would still be validated, converted, annotated, etc.
 
@@ -27,24 +29,14 @@ Let's imagine you want to get the client's IP address/host inside of your *path
 
 For that you need to access the request directly.
 
-### Import the `Request`
-
-First, import the `Request` class from Starlette:
-
-```Python hl_lines="2"
-{!./src/using_request_directly/tutorial001.py!}
+```Python hl_lines="1  7 8"
+{!../../../docs_src/using_request_directly/tutorial001.py!}
 ```
 
-### Declare the `Request` parameter
-
-Then declare a *path operation function* parameter with the type being the `Request` class:
-
-```Python hl_lines="8"
-{!./src/using_request_directly/tutorial001.py!}
-```
+By declaring a *path operation function* parameter with the type being the `Request` **FastAPI** will know to pass the `Request` in that parameter.
 
 !!! tip
-    Note that in this case, we are declaring a path parameter besides the request parameter.
+    Note that in this case, we are declaring a path parameter beside the request parameter.
 
     So, the path parameter will be extracted, validated, converted to the specified type and annotated with OpenAPI.
 
@@ -53,3 +45,8 @@ Then declare a *path operation function* parameter with the type being the `Requ
 ## `Request` documentation
 
 You can read more details about the <a href="https://www.starlette.io/requests/" class="external-link" target="_blank">`Request` object in the official Starlette documentation site</a>.
+
+!!! note "Technical Details"
+    You could also use `from starlette.requests import Request`.
+
+    **FastAPI** provides it directly just as a convenience for you, the developer. But it comes directly from Starlette.

docs/en/docs/advanced/websockets.md

@@ -1,3 +1,4 @@
+# WebSockets
 
 You can use <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API" class="external-link" target="_blank">WebSockets</a> with **FastAPI**.
 
@@ -23,27 +24,29 @@ In production you would have one of the options above.
 
 But it's the simplest way to focus on the server-side of WebSockets and have a working example:
 
-```Python hl_lines="2 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 42 43 44"
-{!./src/websockets/tutorial001.py!}
+```Python hl_lines="2  6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38  41 42 43"
+{!../../../docs_src/websockets/tutorial001.py!}
 ```
 
 ## Create a `websocket`
 
 In your **FastAPI** application, create a `websocket`:
 
-```Python hl_lines="3 47 48"
-{!./src/websockets/tutorial001.py!}
+```Python hl_lines="1 46 47"
+{!../../../docs_src/websockets/tutorial001.py!}
 ```
 
-!!! tip
-    In this example we are importing `WebSocket` from `starlette.websockets` to use it in the type declaration in the WebSocket route function.
+!!! note "Technical Details"
+    You could also use `from starlette.websockets import WebSocket`.
+
+    **FastAPI** provides the same `WebSocket` directly just as a convenience for you, the developer. But it comes directly from Starlette.
 
 ## Await for messages and send messages
 
 In your WebSocket route you can `await` for messages and send messages.
 
-```Python hl_lines="49 50 51 52 53"
-{!./src/websockets/tutorial001.py!}
+```Python hl_lines="48 49 50 51 52"
+{!../../../docs_src/websockets/tutorial001.py!}
 ```
 
 You can receive and send binary, text, and JSON data.
@@ -61,8 +64,8 @@ In WebSocket endpoints you can import from `fastapi` and use:
 
 They work the same way as for other FastAPI endpoints/*path operations*:
 
-```Python hl_lines="55 56 57 58 59 60 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78"
-{!./src/websockets/tutorial002.py!}
+```Python hl_lines="53 54 55 56 57 58  61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76"
+{!../../../docs_src/websockets/tutorial002.py!}
 ```
 
 !!! info
@@ -76,7 +79,6 @@ They work the same way as for other FastAPI endpoints/*path operations*:
 
 To learn more about the options, check Starlette's documentation for:
 
-* <a href="https://www.starlette.io/applications/" class="external-link" target="_blank">Applications (`websocket_route`)</a>.
 * <a href="https://www.starlette.io/websockets/" class="external-link" target="_blank">The `WebSocket` class</a>.
 * <a href="https://www.starlette.io/endpoints/#websocketendpoint" class="external-link" target="_blank">Class-based WebSocket handling</a>.
 
@@ -84,10 +86,16 @@ To learn more about the options, check Starlette's documentation for:
 
 If your file is named `main.py`, run your application with:
 
-```bash
-uvicorn main:app --reload
+<div class="termy">
+
+```console
+$ uvicorn main:app --reload
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
 ```
 
+</div>
+
 Open your browser at <a href="http://127.0.0.1:8000" class="external-link" target="_blank">http://127.0.0.1:8000</a>.
 
 You will see a simple page like:

docs/en/docs/advanced/wsgi.md

@@ -0,0 +1,37 @@
+# Including WSGI - Flask, Django, others
+
+You can mount WSGI applications as you saw with [Sub Applications - Behind a Proxy, Mounts](./sub-applications-proxy.md){.internal-link target=_blank}.
+
+For that, you can use the `WSGIMiddleware` and use it to wrap your WSGI application, for example, Flask, Django, etc.
+
+## Using `WSGIMiddleware`
+
+You need to import `WSGIMiddleware`.
+
+Then wrap the WSGI (e.g. Flask) app with the middleware.
+
+And then mount that under a path.
+
+```Python hl_lines="1  3  22"
+{!../../../docs_src/wsgi/tutorial001.py!}
+```
+
+## Check it
+
+Now, every request under the path `/v1/` will be handled by the Flask application.
+
+And the rest will be handled by **FastAPI**.
+
+If you run it with Uvicorn and go to <a href="http://localhost:8000/v1/" class="external-link" target="_blank">http://localhost:8000/v1/</a> you will see the response from Flask:
+
+```txt
+Hello, World from Flask!
+```
+
+And if you go to <a href="http://localhost:8000/v2" class="external-link" target="_blank">http://localhost:8000/v2</a> you will see the response from FastAPI:
+
+```JSON
+{
+    "message": "Hello World"
+}
+```

docs/en/docs/alternatives.md

@@ -1,3 +1,5 @@
+# Alternatives, Inspiration and Comparisons
+
 What inspired **FastAPI**, how it compares to other alternatives and what it learned from them.
 
 ## Intro

docs/en/docs/async.md

@@ -1,3 +1,5 @@
+# Concurrency and async / await
+
 Details about the `async def` syntax for *path operation functions* and some background about asynchronous code, concurrency, and parallelism.
 
 ## In a hurry?

docs/en/docs/benchmarks.md

@@ -1,3 +1,5 @@
+# Benchmarks
+
 Independent TechEmpower benchmarks show **FastAPI** applications running under Uvicorn as <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">one of the fastest Python frameworks available</a>, only below Starlette and Uvicorn themselves (used internally by FastAPI). (*)
 
 But when checking benchmarks and comparisons you should have the following in mind.

docs/en/docs/contributing.md

@@ -0,0 +1,483 @@
+# Development - Contributing
+
+First, you might want to see the basic ways to [help FastAPI and get help](help-fastapi.md){.internal-link target=_blank}.
+
+## Developing
+
+If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
+
+### Virtual environment with `venv`
+
+You can create a virtual environment in a directory using Python's `venv` module:
+
+<div class="termy">
+
+```console
+$ python -m venv env
+```
+
+</div>
+
+That will create a directory `./env/` with the Python binaries and then you will be able to install packages for that isolated environment.
+
+### Activate the environment
+
+Activate the new environment with:
+
+<div class="termy">
+
+```console
+$ source ./env/bin/activate
+```
+
+</div>
+
+Or in Windows' PowerShell:
+
+<div class="termy">
+
+```console
+$ .\env\Scripts\Activate.ps1
+```
+
+</div>
+
+Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
+
+<div class="termy">
+
+```console
+$ source ./env/Scripts/activate
+```
+
+</div>
+
+To check it worked, use:
+
+<div class="termy">
+
+```console
+$ which pip
+
+some/directory/fastapi/env/bin/pip
+```
+
+</div>
+
+If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
+
+Or in Windows PowerShell:
+
+<div class="termy">
+
+```console
+$ Get-Command pip
+
+some/directory/fastapi/env/bin/pip
+```
+
+</div>
+
+!!! tip
+    Every time you install a new package with `pip` under that environment, activate the environment again.
+
+    This makes sure that if you use a terminal program installed by that package (like `flit`), you use the one from your local environment and not any other that could be installed globally.
+
+### Flit
+
+**FastAPI** uses <a href="https://flit.readthedocs.io/en/latest/index.html" class="external-link" target="_blank">Flit</a> to build, package and publish the project.
+
+After activating the environment as described above, install `flit`:
+
+<div class="termy">
+
+```console
+$ pip install flit
+
+---> 100%
+```
+
+</div>
+
+Now re-activate the environment to make sure you are using the `flit` you just installed (and not a global one).
+
+And now use `flit` to install the development dependencies:
+
+<div class="termy">
+
+```console
+$ flit install --deps develop --symlink
+
+---> 100%
+```
+
+</div>
+
+It will install all the dependencies and your local FastAPI in your local environment.
+
+#### Using your local FastAPI
+
+If you create a Python file that imports and uses FastAPI, and run it with the Python from your local environment, it will use your local FastAPI source code.
+
+And if you update that local FastAPI source code, as it is installed with `--symlink`, when you run that Python file again, it will use the fresh version of FastAPI you just edited.
+
+That way, you don't have to "install" your local version to be able to test every change.
+
+### Format
+
+There is a script that you can run that will format and clean all your code:
+
+<div class="termy">
+
+```console
+$ bash scripts/format.sh
+```
+
+</div>
+
+It will also auto-sort all your imports.
+
+For it to sort them correctly, you need to have FastAPI installed locally in your environment, with the command in the section above:
+
+<div class="termy">
+
+```console
+$ flit install --symlink
+
+---> 100%
+```
+
+</div>
+
+### Format imports
+
+There is another script that formats all the imports and makes sure you don't have unused imports:
+
+<div class="termy">
+
+```console
+$ bash scripts/format-imports.sh
+```
+
+</div>
+
+As it runs one command after the other and modifies and reverts many files, it takes a bit longer to run, so it might be easier to use `scripts/format.sh` frequently and `scripts/format-imports.sh` only before committing.
+
+## Docs
+
+First, make sure you set up your environment as described above, that will install all the requirements.
+
+The documentation uses <a href="https://www.mkdocs.org/" class="external-link" target="_blank">MkDocs</a>.
+
+And there are extra tools/scripts in place to handle translations in `./scripts/docs.py`.
+
+!!! tip
+    You don't need to see the code in `./scripts/docs.py`, you just use it in the command line.
+
+All the documentation is in Markdown format in the directory `./docs/en/`.
+
+Many of the tutorials have blocks of code.
+
+In most of the cases, these blocks of code are actual complete applications that can be run as is.
+
+In fact, those blocks of code are not written inside the Markdown, they are Python files in the `./docs_src/` directory.
+
+And those Python files are included/injected in the documentation when generating the site.
+
+### Docs for tests
+
+Most of the tests actually run against the example source files in the documentation.
+
+This helps making sure that:
+
+* The documentation is up to date.
+* The documentation examples can be run as is.
+* Most of the features are covered by the documentation, ensured by test coverage.
+
+During local development, there is a script that builds the site and checks for any changes, live-reloading:
+
+<div class="termy">
+
+```console
+$ python ./scripts/docs.py live
+
+<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
+<span style="color: green;">[INFO]</span> Start watching changes
+<span style="color: green;">[INFO]</span> Start detecting changes
+```
+
+</div>
+
+It will serve the documentation on `http://127.0.0.1:8008`.
+
+That way, you can edit the documentation/source files and see the changes live.
+
+#### Typer CLI (optional)
+
+The instructions here show you how to use the script at `./scripts/docs.py` with the `python` program directly.
+
+But you can also use <a href="https://typer.tiangolo.com/typer-cli/" class="external-link" target="_blank">Typer CLI</a>, and you will get autocompletion in your terminal for the commands after installing completion.
+
+If you install Typer CLI, you can install completion with:
+
+<div class="termy">
+
+```console
+$ typer --install-completion
+
+zsh completion installed in /home/user/.bashrc.
+Completion will take effect once you restart the terminal.
+```
+
+</div>
+
+### Apps and docs at the same time
+
+If you run the examples with, e.g.:
+
+<div class="termy">
+
+```console
+$ uvicorn tutorial001:app --reload
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+</div>
+
+as Uvicorn by default will use the port `8000`, the documentation on port `8008` won't clash.
+
+### Translations
+
+Help with translations is VERY MUCH appreciated! And it can't be done without the help from the community. 🌎 🚀
+
+Here are the steps to help with translations.
+
+#### Tips and guidelines
+
+* Add a single Pull Request per page translated. That will make it much easier for others to review it.
+
+For the languages I don't speak, I'll wait for several others to review the translation before merging.
+
+* You can also check if there are translations for your language and add a review to them, that will help me know that the translation is correct and I can merge it.
+
+* Use the same Python examples and only translate the text in the docs. You don't have to change anything for this to work.
+
+* Use the same images, file names, and links. You don't have to change anything for it to work.
+
+* To check the 2-letter code for the language you want to translate you can use the table <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes" class="external-link" target="_blank">List of ISO 639-1 codes</a>.
+
+#### Existing language
+
+Let's say you want to translate a page for a language that already has translations for some pages, like Spanish.
+
+In the case of Spanish, the 2-letter code is `es`. So, the directory for Spanish translations is located at `docs/es/`.
+
+!!! tip
+    The main ("official") language is English, located at `docs/en/`.
+
+Now run the live server for the docs in Spanish:
+
+<div class="termy">
+
+```console
+// Use the command "live" and pass the language code as a CLI argument
+$ python ./scripts/docs.py live es
+
+<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008
+<span style="color: green;">[INFO]</span> Start watching changes
+<span style="color: green;">[INFO]</span> Start detecting changes
+```
+
+</div>
+
+Now you can go to <a href="http://127.0.0.1:8008" class="external-link" target="_blank">http://127.0.0.1:8008</a> and see your changes live.
+
+If you look at the FastAPI docs website, you will see that every language has all the pages. But some are not translated and have a notification about the the translation is missing.
+
+But when you run it locally like this, you will only see the pages that are already translated.
+
+Now let's say that you want to add a translation for the section [Features](features.md){.internal-link target=_blank}.
+
+* Copy the file at:
+
+```
+docs/en/docs/features.md
+```
+
+* Paste it in exactly the same location but for the language you want to translate, e.g.:
+
+```
+docs/es/docs/features.md
+```
+
+!!! tip
+    Notice that the only change in the path and file name is the language code, from `en` to `es`.
+
+* Now open the MkDocs config file for English at:
+
+```
+docs/en/docs/mkdocs.yml
+```
+
+* Find the place where that `docs/features.md` is located in the config file. Somewhere like:
+
+```YAML hl_lines="8"
+site_name: FastAPI
+# More stuff
+nav:
+- FastAPI: index.md
+- Languages:
+  - en: /
+  - es: /es/
+- features.md
+```
+
+* Open the MkDocs config file for the language you are editing, e.g.:
+
+```
+docs/es/docs/mkdocs.yml
+```
+
+* Add it there at the exact same location it was for English, e.g.:
+
+```YAML hl_lines="8"
+site_name: FastAPI
+# More stuff
+nav:
+- FastAPI: index.md
+- Languages:
+  - en: /
+  - es: /es/
+- features.md
+```
+
+Make sure that if there are other entries, the new entry with your translation is exactly in the same order as in the English version.
+
+If you go to your browser you will see that now the docs show your new section. 🎉
+
+Now you can translate it all and see how it looks as you save the file.
+
+#### New Language
+
+Let's say that you want to add translations for a language that is not yet translated, not even some pages.
+
+Let's say you want to add translations for Creole, and it's not yet there in the docs.
+
+Checking the link from above, the code for "Creole" is `ht`.
+
+The next step is to run the script to generate a new translation directory:
+
+<div class="termy">
+
+```console
+// Use the command new-lang, pass the language code as a CLI argument
+$ python ./scripts/docs.py new-lang ht
+
+Successfully initialized: docs/ht
+Updating ht
+Updating en
+```
+
+</div>
+
+Now you can check in your code editor the newly created directory `docs/ht/`.
+
+Start by translating the main page, `docs/ht/index.md`.
+
+Then you can continue with the previous instructions, for an "Existing Language".
+
+##### New Language not supported
+
+If when running the live server script you get an error about the language not being supported, something like:
+
+```
+ raise TemplateNotFound(template)
+jinja2.exceptions.TemplateNotFound: partials/language/xx.html
+```
+
+That means that the theme doesn't support that language (in this case, with a fake 2-letter code of `xx`).
+
+But don't worry, you can set the theme language to English and then translate the content of the docs.
+
+If you need to do that, edit the `mkdocs.yml` for your new language, it will have something like:
+
+```YAML hl_lines="5"
+site_name: FastAPI
+# More stuff
+theme:
+  # More stuff
+  language: xx
+```
+
+Change that language from `xx` (from your language code) to `en`.
+
+Then you can start the live server again.
+
+#### Preview the result
+
+When you use the script at `./scripts/docs.py` with the `live` command it only shows the files and translations available for the current language.
+
+But once you are done, you can test it all as it would look online.
+
+To do that, first build all the docs:
+
+<div class="termy">
+
+```console
+// Use the command "build-all", this will take a bit
+$ python ./scripts/docs.py build-all
+
+Updating es
+Updating en
+Building docs for: en
+Building docs for: es
+Successfully built docs for: es
+Copying en index.md to README.md
+```
+
+</div>
+
+That generates all the docs at `./docs_build/` for each language. This includes adding any files with missing translations, with a note saying that "this file doesn't have a translation yet". But you don't have to do anything with that directory.
+
+Then it builds all those independent MkDocs sites for each language, combines them, and generates the final output at `./site/`.
+
+Then you can serve that with the command `serve`:
+
+<div class="termy">
+
+```console
+// Use the command "serve" after running "build-all"
+$ python ./scripts/docs.py serve
+
+Warning: this is a very simple server. For development, use mkdocs serve instead.
+This is here only to preview a site with translations already built.
+Make sure you run the build-all command first.
+Serving at: http://127.0.0.1:8008
+```
+
+</div>
+
+## Tests
+
+There is a script that you can run locally to test all the code and generate coverage reports in HTML:
+
+<div class="termy">
+
+```console
+$ bash scripts/test-cov-html.sh
+```
+
+</div>
+
+This command generates a directory `./htmlcov/`, if you open the file `./htmlcov/index.html` in your browser, you can explore interactively the regions of code that are covered by the tests, and notice if there is any region missing.
+
+### Tests in your editor
+
+If you want to use the integrated tests in your editor add `./docs/src` to your `PYTHONPATH` variable.
+
+For example, in VS Code you can create a file `.env` with:
+
+```env
+PYTHONPATH=./docs/src
+```

docs/en/docs/css/termynal.css

@@ -0,0 +1,108 @@
+/**
+ * termynal.js
+ *
+ * @author Ines Montani <ines@ines.io>
+ * @version 0.0.1
+ * @license MIT
+ */
+
+:root {
+    --color-bg: #252a33;
+    --color-text: #eee;
+    --color-text-subtle: #a2a2a2;
+}
+
+[data-termynal] {
+    width: 750px;
+    max-width: 100%;
+    background: var(--color-bg);
+    color: var(--color-text);
+    font-size: 18px;
+    /* font-family: 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace; */
+    font-family: 'Roboto Mono', 'Fira Mono', Consolas, Menlo, Monaco, 'Courier New', Courier, monospace;
+    border-radius: 4px;
+    padding: 75px 45px 35px;
+    position: relative;
+    -webkit-box-sizing: border-box;
+            box-sizing: border-box;
+}
+
+[data-termynal]:before {
+    content: '';
+    position: absolute;
+    top: 15px;
+    left: 15px;
+    display: inline-block;
+    width: 15px;
+    height: 15px;
+    border-radius: 50%;
+    /* A little hack to display the window buttons in one pseudo element. */
+    background: #d9515d;
+    -webkit-box-shadow: 25px 0 0 #f4c025, 50px 0 0 #3ec930;
+            box-shadow: 25px 0 0 #f4c025, 50px 0 0 #3ec930;
+}
+
+[data-termynal]:after {
+    content: 'bash';
+    position: absolute;
+    color: var(--color-text-subtle);
+    top: 5px;
+    left: 0;
+    width: 100%;
+    text-align: center;
+}
+
+a[data-terminal-control] {
+    text-align: right;
+    display: block;
+    color: #aebbff;
+}
+
+[data-ty] {
+    display: block;
+    line-height: 2;
+}
+
+[data-ty]:before {
+    /* Set up defaults and ensure empty lines are displayed. */
+    content: '';
+    display: inline-block;
+    vertical-align: middle;
+}
+
+[data-ty="input"]:before,
+[data-ty-prompt]:before {
+    margin-right: 0.75em;
+    color: var(--color-text-subtle);
+}
+
+[data-ty="input"]:before {
+    content: '$';
+}
+
+[data-ty][data-ty-prompt]:before {
+    content: attr(data-ty-prompt);
+}
+
+[data-ty-cursor]:after {
+    content: attr(data-ty-cursor);
+    font-family: monospace;
+    margin-left: 0.5em;
+    -webkit-animation: blink 1s infinite;
+            animation: blink 1s infinite;
+}
+
+
+/* Cursor animation */
+
+@-webkit-keyframes blink {
+    50% {
+        opacity: 0;
+    }
+}
+
+@keyframes blink {
+    50% {
+        opacity: 0;
+    }
+}

docs/en/docs/deployment.md

@@ -1,3 +1,5 @@
+# Deployment
+
 Deploying a **FastAPI** application is relatively easy.
 
 There are several ways to do it depending on your specific use case and the tools that you use.
@@ -188,18 +190,28 @@ def read_item(item_id: int, q: str = None):
 * Go to the project directory (in where your `Dockerfile` is, containing your `app` directory).
 * Build your FastAPI image:
 
-```bash
-docker build -t myimage .
+<div class="termy">
+
+```console
+$ docker build -t myimage .
+
+---> 100%
 ```
 
+</div>
+
 ### Start the Docker container
 
 * Run a container based on your image:
 
-```bash
-docker run -d --name mycontainer -p 80:80 myimage
+<div class="termy">
+
+```console
+$ docker run -d --name mycontainer -p 80:80 myimage
 ```
 
+</div>
+
 Now you have an optimized FastAPI server in a Docker container. Auto-tuned for your current server (and number of CPU cores).
 
 ### Check it
@@ -319,30 +331,54 @@ You just need to install an ASGI compatible server like:
 
 * <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>, a lightning-fast ASGI server, built on uvloop and httptools.
 
-```bash
-pip install uvicorn
+<div class="termy">
+
+```console
+$ pip install uvicorn
+
+---> 100%
 ```
 
+</div>
+
 * <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
 
-```bash
-pip install hypercorn
+<div class="termy">
+
+```console
+$ pip install hypercorn
+
+---> 100%
 ```
 
+</div>
+
 ...or any other ASGI server.
 
 And run your application the same way you have done in the tutorials, but without the `--reload` option, e.g.:
 
-```bash
-uvicorn main:app --host 0.0.0.0 --port 80
+<div class="termy">
+
+```console
+$ uvicorn main:app --host 0.0.0.0 --port 80
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
 ```
 
+</div>
+
 or with Hypercorn:
 
-```bash
-hypercorn main:app --bind 0.0.0.0:80
+<div class="termy">
+
+```console
+$ hypercorn main:app --bind 0.0.0.0:80
+
+Running on 0.0.0.0:8080 over http (CTRL + C to quit)
 ```
 
+</div>
+
 You might want to set up some tooling to make sure it is restarted automatically if it stops.
 
 You might also want to install <a href="https://gunicorn.org/" class="external-link" target="_blank">Gunicorn</a> and <a href="https://www.uvicorn.org/#running-with-gunicorn" class="external-link" target="_blank">use it as a manager for Uvicorn</a>, or use Hypercorn with multiple workers.

docs/en/docs/external-links.md

@@ -1,3 +1,5 @@
+# External Links and Articles
+
 **FastAPI** has a great community constantly growing.
 
 There are many posts, articles, tools, and projects, related to **FastAPI**.
@@ -57,6 +59,8 @@ Here's an incomplete list of some of them.
 
 * <a href="https://www.tutlinks.com/create-and-deploy-fastapi-app-to-heroku/" class="external-link" target="_blank">Create and Deploy FastAPI app to Heroku without using Docker</a> by <a href="https://www.linkedin.com/in/navule/" class="external-link" target="_blank">Navule Pavan Kumar Rao</a>.
 
+* <a href="https://iwpnd.pw/articles/2020-03/apache-kafka-fastapi-geostream" class="external-link" target="_blank">Apache Kafka producer and consumer with FastAPI and aiokafka</a> by <a href="https://iwpnd.pw" class="external-link" target="_blank">Benjamin Ramser</a>.
+
 ### Japanese
 
 * <a href="https://qiita.com/mtitg/items/47770e9a562dd150631d" class="external-link" target="_blank">FastAPI｜DB接続してCRUDするPython製APIサーバーを構築</a> by <a href="https://qiita.com/mtitg" class="external-link" target="_blank">@mtitg</a>.

docs/en/docs/features.md

@@ -1,3 +1,4 @@
+# Features
 
 ## FastAPI features
 
@@ -16,11 +17,11 @@ Interactive API documentation and exploration web user interfaces. As the framew
 
 * <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank"><strong>Swagger UI</strong></a>, with interactive exploration, call and test your API directly from the browser.
 
-![Swagger UI interaction](img/index/index-03-swagger-02.png)
+![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png)
 
 * Alternative API documentation with <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank"><strong>ReDoc</strong></a>.
 
-![ReDoc](img/index/index-06-redoc-02.png)
+![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png)
 
 ### Just Modern Python
 
@@ -82,11 +83,11 @@ Here's how your editor might help you:
 
 * in <a href="https://code.visualstudio.com/" class="external-link" target="_blank">Visual Studio Code</a>:
 
-![editor support](img/vscode-completion.png)
+![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png)
 
 * in <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>:
 
-![editor support](img/pycharm-completion.png)
+![editor support](https://fastapi.tiangolo.com/img/pycharm-completion.png)
 
 You will get completion in code you might even consider impossible before. As for example, the `price` key inside a JSON body (that could have been nested) that comes from a request.
 

docs/en/docs/help-fastapi.md

@@ -1,3 +1,5 @@
+# Help FastAPI - Get Help
+
 Do you like **FastAPI**?
 
 Would you like to help FastAPI, other users, and the author?

docs/en/docs/history-design-future.md

@@ -1,3 +1,5 @@
+# History, Design and Future
+
 Some time ago, <a href="https://github.com/tiangolo/fastapi/issues/3#issuecomment-454956920" class="external-link" target="_blank">a **FastAPI** user asked</a>:
 
 > What’s the history of this project? It seems to have come from nowhere to awesome in a few weeks [...]