mirror of https://github.com/tiangolo/fastapi.git
⬆️ Upgrade to MkDocs Material 5 and update docs scripts (#1225)
* ⬆️ Upgrade mkdocs.yml configs for MkDocs Material 5 * ✨ Update docs.py to always update mkdocs.yml * 🌐 Update mkdocs.yml for translations * 🔧 Update MkDocs config * ✨ Add tabs for alternative options * ⬆️ Update termynal setup with new CSS classes * 🔧 Sync / Update mkdocs.yml for languages
This commit is contained in:
Sebastián Ramírez
GitHub
parent
7372f6ba11
commit
483bce3ae1
|
|
@ -15,35 +15,37 @@ An <a href="https://en.wikipedia.org/wiki/Environment_variable" class="external-
|
|||
|
||||
You can create and use environment variables in the shell, without needing Python:
|
||||
|
||||
<div class="termy">
|
||||
=== "Linux, macOS, Windows Bash"
|
||||
|
||||
```console
|
||||
// You could create an env var MY_NAME with
|
||||
$ export MY_NAME="Wade Wilson"
|
||||
<div class="termy">
|
||||
|
||||
// Then you could use it with other programs, like
|
||||
$ echo "Hello $MY_NAME"
|
||||
```console
|
||||
// You could create an env var MY_NAME with
|
||||
$ export MY_NAME="Wade Wilson"
|
||||
|
||||
Hello Wade Wilson
|
||||
```
|
||||
// Then you could use it with other programs, like
|
||||
$ echo "Hello $MY_NAME"
|
||||
|
||||
</div>
|
||||
Hello Wade Wilson
|
||||
```
|
||||
|
||||
Or in PowerShell in Windows:
|
||||
</div>
|
||||
|
||||
<div class="termy">
|
||||
=== "Windows PowerShell"
|
||||
|
||||
```console
|
||||
// Create an env var MY_NAME
|
||||
$ $Env:MY_NAME = "Wade Wilson"
|
||||
<div class="termy">
|
||||
|
||||
// Use it with other programs, like
|
||||
$ echo "Hello $Env:MY_NAME"
|
||||
```console
|
||||
// Create an env var MY_NAME
|
||||
$ $Env:MY_NAME = "Wade Wilson"
|
||||
|
||||
Hello Wade Wilson
|
||||
```
|
||||
// Use it with other programs, like
|
||||
$ echo "Hello $Env:MY_NAME"
|
||||
|
||||
</div>
|
||||
Hello Wade Wilson
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
### Read env vars in Python
|
||||
|
||||
|
|
|
|||
|
|
@ -24,59 +24,67 @@ That will create a directory `./env/` with the Python binaries and then you will
|
|||
|
||||
Activate the new environment with:
|
||||
|
||||
<div class="termy">
|
||||
=== "Linux, macOS"
|
||||
|
||||
```console
|
||||
$ source ./env/bin/activate
|
||||
```
|
||||
<div class="termy">
|
||||
|
||||
</div>
|
||||
```console
|
||||
$ source ./env/bin/activate
|
||||
```
|
||||
|
||||
Or in Windows' PowerShell:
|
||||
</div>
|
||||
|
||||
<div class="termy">
|
||||
=== "Windows PowerShell"
|
||||
|
||||
```console
|
||||
$ .\env\Scripts\Activate.ps1
|
||||
```
|
||||
<div class="termy">
|
||||
|
||||
</div>
|
||||
```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>):
|
||||
</div>
|
||||
|
||||
<div class="termy">
|
||||
=== "Windows Bash"
|
||||
|
||||
```console
|
||||
$ source ./env/Scripts/activate
|
||||
```
|
||||
Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
|
||||
|
||||
</div>
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ source ./env/Scripts/activate
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
To check it worked, use:
|
||||
|
||||
<div class="termy">
|
||||
=== "Linux, macOS, Windows Bash"
|
||||
|
||||
```console
|
||||
$ which pip
|
||||
<div class="termy">
|
||||
|
||||
some/directory/fastapi/env/bin/pip
|
||||
```
|
||||
```console
|
||||
$ which pip
|
||||
|
||||
</div>
|
||||
some/directory/fastapi/env/bin/pip
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
=== "Windows PowerShell"
|
||||
|
||||
<div class="termy">
|
||||
|
||||
```console
|
||||
$ Get-Command 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.
|
||||
|
|
@ -103,27 +111,31 @@ Now re-activate the environment to make sure you are using the `flit` you just i
|
|||
|
||||
And now use `flit` to install the development dependencies:
|
||||
|
||||
<div class="termy">
|
||||
=== "Linux, macOS"
|
||||
|
||||
```console
|
||||
$ flit install --deps develop --symlink
|
||||
<div class="termy">
|
||||
|
||||
---> 100%
|
||||
```
|
||||
```console
|
||||
$ flit install --deps develop --symlink
|
||||
|
||||
</div>
|
||||
---> 100%
|
||||
```
|
||||
|
||||
If you are on Windows, use `--pth-file` instead of `--symlink`:
|
||||
</div>
|
||||
|
||||
<div class="termy">
|
||||
=== "Windows"
|
||||
|
||||
```console
|
||||
$ flit install --deps develop --pth-file
|
||||
If you are on Windows, use `--pth-file` instead of `--symlink`:
|
||||
|
||||
---> 100%
|
||||
```
|
||||
<div class="termy">
|
||||
|
||||
</div>
|
||||
```console
|
||||
$ flit install --deps develop --pth-file
|
||||
|
||||
---> 100%
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
It will install all the dependencies and your local FastAPI in your local environment.
|
||||
|
||||
|
|
|
|||
|
|
@ -329,55 +329,61 @@ You can deploy **FastAPI** directly without Docker too.
|
|||
|
||||
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.
|
||||
=== "Uvicorn"
|
||||
|
||||
<div class="termy">
|
||||
* <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>, a lightning-fast ASGI server, built on uvloop and httptools.
|
||||
|
||||
```console
|
||||
$ pip install uvicorn
|
||||
<div class="termy">
|
||||
|
||||
---> 100%
|
||||
```
|
||||
```console
|
||||
$ pip install uvicorn
|
||||
|
||||
</div>
|
||||
---> 100%
|
||||
```
|
||||
|
||||
* <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
|
||||
</div>
|
||||
|
||||
<div class="termy">
|
||||
=== "Hypercorn"
|
||||
|
||||
```console
|
||||
$ pip install hypercorn
|
||||
* <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
|
||||
|
||||
---> 100%
|
||||
```
|
||||
<div class="termy">
|
||||
|
||||
</div>
|
||||
```console
|
||||
$ pip install hypercorn
|
||||
|
||||
...or any other ASGI server.
|
||||
---> 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.:
|
||||
|
||||
<div class="termy">
|
||||
=== "Uvicorn"
|
||||
|
||||
```console
|
||||
$ uvicorn main:app --host 0.0.0.0 --port 80
|
||||
<div class="termy">
|
||||
|
||||
<span style="color: green;">INFO</span>: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
|
||||
```
|
||||
```console
|
||||
$ uvicorn main:app --host 0.0.0.0 --port 80
|
||||
|
||||
</div>
|
||||
<span style="color: green;">INFO</span>: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
or with Hypercorn:
|
||||
</div>
|
||||
|
||||
<div class="termy">
|
||||
=== "Hypercorn"
|
||||
|
||||
```console
|
||||
$ hypercorn main:app --bind 0.0.0.0:80
|
||||
<div class="termy">
|
||||
|
||||
Running on 0.0.0.0:8080 over http (CTRL + C to quit)
|
||||
```
|
||||
```console
|
||||
$ hypercorn main:app --bind 0.0.0.0:80
|
||||
|
||||
</div>
|
||||
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ function setupTermynal() {
|
|||
|
||||
function createTermynals() {
|
||||
document
|
||||
.querySelectorAll(`.${termynalActivateClass} .codehilite`)
|
||||
.querySelectorAll(`.${termynalActivateClass} .highlight`)
|
||||
.forEach(node => {
|
||||
const text = node.textContent;
|
||||
const lines = text.split("\n");
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@ theme:
|
|||
palette:
|
||||
primary: teal
|
||||
accent: amber
|
||||
icon:
|
||||
repo: fontawesome/brands/github-alt
|
||||
logo: img/icon-white.svg
|
||||
favicon: img/favicon.png
|
||||
language: en
|
||||
|
|
@ -129,19 +131,20 @@ markdown_extensions:
|
|||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_div_format ''
|
||||
- pymdownx.tabbed
|
||||
extra:
|
||||
social:
|
||||
- type: github
|
||||
- icon: fontawesome/brands/github-alt
|
||||
link: https://github.com/tiangolo/typer
|
||||
- type: twitter
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: https://twitter.com/tiangolo
|
||||
- type: linkedin
|
||||
- icon: fontawesome/brands/linkedin
|
||||
link: https://www.linkedin.com/in/tiangolo
|
||||
- type: rss
|
||||
- icon: fontawesome/brands/dev
|
||||
link: https://dev.to/tiangolo
|
||||
- type: medium
|
||||
- icon: fontawesome/brands/medium
|
||||
link: https://medium.com/@tiangolo
|
||||
- type: globe
|
||||
- icon: fontawesome/solid/globe
|
||||
link: https://tiangolo.com
|
||||
extra_css:
|
||||
- css/termynal.css
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@ theme:
|
|||
palette:
|
||||
primary: teal
|
||||
accent: amber
|
||||
icon:
|
||||
repo: fontawesome/brands/github-alt
|
||||
logo: https://fastapi.tiangolo.com/img/icon-white.svg
|
||||
favicon: https://fastapi.tiangolo.com/img/favicon.png
|
||||
language: es
|
||||
|
|
@ -37,19 +39,20 @@ markdown_extensions:
|
|||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_div_format ''
|
||||
- pymdownx.tabbed
|
||||
extra:
|
||||
social:
|
||||
- type: github
|
||||
- icon: fontawesome/brands/github-alt
|
||||
link: https://github.com/tiangolo/typer
|
||||
- type: twitter
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: https://twitter.com/tiangolo
|
||||
- type: linkedin
|
||||
- icon: fontawesome/brands/linkedin
|
||||
link: https://www.linkedin.com/in/tiangolo
|
||||
- type: rss
|
||||
- icon: fontawesome/brands/dev
|
||||
link: https://dev.to/tiangolo
|
||||
- type: medium
|
||||
- icon: fontawesome/brands/medium
|
||||
link: https://medium.com/@tiangolo
|
||||
- type: globe
|
||||
- icon: fontawesome/solid/globe
|
||||
link: https://tiangolo.com
|
||||
extra_css:
|
||||
- https://fastapi.tiangolo.com/css/termynal.css
|
||||
|
|
@ -58,3 +61,5 @@ extra_javascript:
|
|||
- https://unpkg.com/mermaid@8.4.6/dist/mermaid.min.js
|
||||
- https://fastapi.tiangolo.com/js/termynal.js
|
||||
- https://fastapi.tiangolo.com/js/custom.js
|
||||
- https://fastapi.tiangolo.com/js/chat.js
|
||||
- https://sidecar.gitter.im/dist/sidecar.v1.js
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@ theme:
|
|||
palette:
|
||||
primary: teal
|
||||
accent: amber
|
||||
icon:
|
||||
repo: fontawesome/brands/github-alt
|
||||
logo: https://fastapi.tiangolo.com/img/icon-white.svg
|
||||
favicon: https://fastapi.tiangolo.com/img/favicon.png
|
||||
language: pt
|
||||
|
|
@ -37,19 +39,20 @@ markdown_extensions:
|
|||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_div_format ''
|
||||
- pymdownx.tabbed
|
||||
extra:
|
||||
social:
|
||||
- type: github
|
||||
- icon: fontawesome/brands/github-alt
|
||||
link: https://github.com/tiangolo/typer
|
||||
- type: twitter
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: https://twitter.com/tiangolo
|
||||
- type: linkedin
|
||||
- icon: fontawesome/brands/linkedin
|
||||
link: https://www.linkedin.com/in/tiangolo
|
||||
- type: rss
|
||||
- icon: fontawesome/brands/dev
|
||||
link: https://dev.to/tiangolo
|
||||
- type: medium
|
||||
- icon: fontawesome/brands/medium
|
||||
link: https://medium.com/@tiangolo
|
||||
- type: globe
|
||||
- icon: fontawesome/solid/globe
|
||||
link: https://tiangolo.com
|
||||
extra_css:
|
||||
- https://fastapi.tiangolo.com/css/termynal.css
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@ theme:
|
|||
palette:
|
||||
primary: teal
|
||||
accent: amber
|
||||
icon:
|
||||
repo: fontawesome/brands/github-alt
|
||||
logo: https://fastapi.tiangolo.com/img/icon-white.svg
|
||||
favicon: https://fastapi.tiangolo.com/img/favicon.png
|
||||
language: zh
|
||||
|
|
@ -37,19 +39,20 @@ markdown_extensions:
|
|||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_div_format ''
|
||||
- pymdownx.tabbed
|
||||
extra:
|
||||
social:
|
||||
- type: github
|
||||
- icon: fontawesome/brands/github-alt
|
||||
link: https://github.com/tiangolo/typer
|
||||
- type: twitter
|
||||
- icon: fontawesome/brands/twitter
|
||||
link: https://twitter.com/tiangolo
|
||||
- type: linkedin
|
||||
- icon: fontawesome/brands/linkedin
|
||||
link: https://www.linkedin.com/in/tiangolo
|
||||
- type: rss
|
||||
- icon: fontawesome/brands/dev
|
||||
link: https://dev.to/tiangolo
|
||||
- type: medium
|
||||
- icon: fontawesome/brands/medium
|
||||
link: https://medium.com/@tiangolo
|
||||
- type: globe
|
||||
- icon: fontawesome/solid/globe
|
||||
link: https://tiangolo.com
|
||||
extra_css:
|
||||
- https://fastapi.tiangolo.com/css/termynal.css
|
||||
|
|
|
|||
|
|
@ -20,6 +20,12 @@ missing_translation_snippet = """
|
|||
"""
|
||||
|
||||
docs_path = Path("docs")
|
||||
en_docs_path = Path("docs/en")
|
||||
en_config_path: Path = en_docs_path / mkdocs_name
|
||||
|
||||
|
||||
def get_en_config() -> dict:
|
||||
return mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def get_lang_paths():
|
||||
|
|
@ -43,39 +49,15 @@ def complete_existing_lang(incomplete: str):
|
|||
yield lang_path.name
|
||||
|
||||
|
||||
@app.command()
|
||||
def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
|
||||
"""
|
||||
Generate a new docs translation directory for the language LANG.
|
||||
|
||||
LANG should be a 2-letter language code, like: en, es, de, pt, etc.
|
||||
"""
|
||||
new_path: Path = Path("docs") / lang
|
||||
if new_path.exists():
|
||||
typer.echo(f"The language was already created: {lang}")
|
||||
raise typer.Abort()
|
||||
new_path.mkdir()
|
||||
en_docs_path = Path("docs/en")
|
||||
en_config_path: Path = en_docs_path / mkdocs_name
|
||||
en_config: dict = mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
|
||||
def get_base_lang_config(lang: str):
|
||||
en_config = get_en_config()
|
||||
fastapi_url_base = "https://fastapi.tiangolo.com/"
|
||||
new_config = {}
|
||||
new_config["site_name"] = en_config["site_name"]
|
||||
new_config["site_description"] = en_config["site_description"]
|
||||
new_config = en_config.copy()
|
||||
new_config["site_url"] = en_config["site_url"] + f"{lang}/"
|
||||
new_config["theme"] = en_config["theme"]
|
||||
new_config["theme"]["logo"] = fastapi_url_base + en_config["theme"]["logo"]
|
||||
new_config["theme"]["favicon"] = fastapi_url_base + en_config["theme"]["favicon"]
|
||||
new_config["theme"]["language"] = lang
|
||||
new_config["repo_name"] = en_config["repo_name"]
|
||||
new_config["repo_url"] = en_config["repo_url"]
|
||||
new_config["edit_uri"] = en_config["edit_uri"]
|
||||
new_config["google_analytics"] = en_config["google_analytics"]
|
||||
new_config["nav"] = en_config["nav"][:2]
|
||||
|
||||
new_config["markdown_extensions"] = en_config["markdown_extensions"]
|
||||
new_config["extra"] = en_config["extra"]
|
||||
|
||||
extra_css = []
|
||||
css: str
|
||||
for css in en_config["extra_css"]:
|
||||
|
|
@ -93,6 +75,22 @@ def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
|
|||
else:
|
||||
extra_js.append(fastapi_url_base + js)
|
||||
new_config["extra_javascript"] = extra_js
|
||||
return new_config
|
||||
|
||||
|
||||
@app.command()
|
||||
def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
|
||||
"""
|
||||
Generate a new docs translation directory for the language LANG.
|
||||
|
||||
LANG should be a 2-letter language code, like: en, es, de, pt, etc.
|
||||
"""
|
||||
new_path: Path = Path("docs") / lang
|
||||
if new_path.exists():
|
||||
typer.echo(f"The language was already created: {lang}")
|
||||
raise typer.Abort()
|
||||
new_path.mkdir()
|
||||
new_config = get_base_lang_config(lang)
|
||||
new_config_path: Path = Path(new_path) / mkdocs_name
|
||||
new_config_path.write_text(
|
||||
yaml.dump(new_config, sort_keys=False, width=200), encoding="utf-8"
|
||||
|
|
@ -280,7 +278,15 @@ def live(
|
|||
def update_config(lang: str):
|
||||
lang_path: Path = docs_path / lang
|
||||
config_path = lang_path / mkdocs_name
|
||||
config: dict = mkdocs.utils.yaml_load(config_path.read_text(encoding="utf-8"))
|
||||
current_config: dict = mkdocs.utils.yaml_load(
|
||||
config_path.read_text(encoding="utf-8")
|
||||
)
|
||||
if lang == "en":
|
||||
config = get_en_config()
|
||||
else:
|
||||
config = get_base_lang_config(lang)
|
||||
config["nav"] = current_config["nav"]
|
||||
config["theme"]["language"] = current_config["theme"]["language"]
|
||||
languages = [{"en": "/"}]
|
||||
for lang in get_lang_paths():
|
||||
if lang.name == "en" or not lang.is_dir():
|
||||
|
|
|
|||
Loading…
Reference in New Issue