✨ Add support for docs translations (fastapi#1168)

* 🌐 Refactor file structure to support internationalization

* ✅ Update tests changed after i18n

* 🔀 Merge Typer style from master

* 🔧 Update MkConfig with Typer-styles

* 🎨 Format mkdocs.yml with cannonical form

* 🎨 Format mkdocs.yml

* 🔧 Update MkDocs config

* ➕ Add docs translation scripts dependencies

* ✨ Add Typer scripts to handle translations

* ✨ Add missing translation snippet to include

* ✨ Update contributing docs, add docs for translations

* 🙈 Add docs_build to gitignore

* 🔧 Update scripts with new locations and docs scripts

* 👷 Update docs deploy action with translations

* 📝 Add note about languages not supported in the theme

* ✨ Add first translation, for Spanish

.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/[email protected]
         with:

.gitignore

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

docs/advanced/additional-responses.md → 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/advanced/additional-status-codes.md → docs/en/docs/advanced/additional-status-codes.md

@@ -1,3 +1,5 @@
+# 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*.
@@ -13,7 +15,7 @@ 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  19"
-{!./src/additional_status_codes/tutorial001.py!}
+{!../../../docs_src/additional_status_codes/tutorial001.py!}
 ```
 
 !!! warning

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

@@ -1,3 +1,5 @@
+# Advanced Dependencies
+
 ## Parameterized dependencies
 
 All the dependencies we have seen are a fixed function or class.
@@ -17,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.
@@ -27,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.
@@ -37,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`.
@@ -55,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/advanced/async-sql-databases.md → 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,15 +79,15 @@ 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
 
 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