From 483bce3ae1a987f6f248cd4bb5b96955652fb0dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Wed, 8 Apr 2020 06:25:01 +0200 Subject: [PATCH] :arrow_up: Upgrade to MkDocs Material 5 and update docs scripts (#1225) * :arrow_up: Upgrade mkdocs.yml configs for MkDocs Material 5 * :sparkles: Update docs.py to always update mkdocs.yml * :globe_with_meridians: Update mkdocs.yml for translations * :wrench: Update MkDocs config * :sparkles: Add tabs for alternative options * :arrow_up: Update termynal setup with new CSS classes * :wrench: Sync / Update mkdocs.yml for languages --- docs/en/docs/advanced/settings.md | 40 ++++++------ docs/en/docs/contributing.md | 100 +++++++++++++++++------------- docs/en/docs/deployment.md | 62 +++++++++--------- docs/en/docs/js/custom.js | 2 +- docs/en/mkdocs.yml | 15 +++-- docs/es/mkdocs.yml | 17 +++-- docs/pt/mkdocs.yml | 15 +++-- docs/zh/mkdocs.yml | 15 +++-- scripts/docs.py | 62 +++++++++--------- 9 files changed, 184 insertions(+), 144 deletions(-) diff --git a/docs/en/docs/advanced/settings.md b/docs/en/docs/advanced/settings.md index f7d957664..f30de226c 100644 --- a/docs/en/docs/advanced/settings.md +++ b/docs/en/docs/advanced/settings.md @@ -15,35 +15,37 @@ An +=== "Linux, macOS, Windows Bash" -```console -// You could create an env var MY_NAME with -$ export MY_NAME="Wade Wilson" +
-// 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" -
+ Hello Wade Wilson + ``` -Or in PowerShell in Windows: + -
+=== "Windows PowerShell" -```console -// Create an env var MY_NAME -$ $Env:MY_NAME = "Wade Wilson" +
-// 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" -
+ Hello Wade Wilson + ``` + +
### Read env vars in Python diff --git a/docs/en/docs/contributing.md b/docs/en/docs/contributing.md index 66fc8efc9..416bc32f8 100644 --- a/docs/en/docs/contributing.md +++ b/docs/en/docs/contributing.md @@ -24,59 +24,67 @@ That will create a directory `./env/` with the Python binaries and then you will Activate the new environment with: -
+=== "Linux, macOS" -```console -$ source ./env/bin/activate -``` +
-
+ ```console + $ source ./env/bin/activate + ``` -Or in Windows' PowerShell: +
-
+=== "Windows PowerShell" -```console -$ .\env\Scripts\Activate.ps1 -``` +
-
+ ```console + $ .\env\Scripts\Activate.ps1 + ``` -Or if you use Bash for Windows (e.g. Git Bash): +
-
+=== "Windows Bash" -```console -$ source ./env/Scripts/activate -``` + Or if you use Bash for Windows (e.g. Git Bash): -
+
+ + ```console + $ source ./env/Scripts/activate + ``` + +
To check it worked, use: -
+=== "Linux, macOS, Windows Bash" -```console -$ which pip +
-some/directory/fastapi/env/bin/pip -``` + ```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: +=== "Windows PowerShell" -
+
-```console -$ Get-Command pip + ```console + $ Get-Command pip + + some/directory/fastapi/env/bin/pip + ``` + +
+ +If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉 -some/directory/fastapi/env/bin/pip -``` -
!!! 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: -
+=== "Linux, macOS" -```console -$ flit install --deps develop --symlink +
----> 100% -``` + ```console + $ flit install --deps develop --symlink -
+ ---> 100% + ``` -If you are on Windows, use `--pth-file` instead of `--symlink`: +
-
+=== "Windows" -```console -$ flit install --deps develop --pth-file + If you are on Windows, use `--pth-file` instead of `--symlink`: ----> 100% -``` +
-
+ ```console + $ flit install --deps develop --pth-file + + ---> 100% + ``` + +
It will install all the dependencies and your local FastAPI in your local environment. diff --git a/docs/en/docs/deployment.md b/docs/en/docs/deployment.md index 8ca7c433f..94ab1b90b 100644 --- a/docs/en/docs/deployment.md +++ b/docs/en/docs/deployment.md @@ -329,55 +329,61 @@ You can deploy **FastAPI** directly without Docker too. You just need to install an ASGI compatible server like: -* Uvicorn, a lightning-fast ASGI server, built on uvloop and httptools. +=== "Uvicorn" -
+ * Uvicorn, a lightning-fast ASGI server, built on uvloop and httptools. -```console -$ pip install uvicorn +
----> 100% -``` + ```console + $ pip install uvicorn -
+ ---> 100% + ``` -* Hypercorn, an ASGI server also compatible with HTTP/2. +
-
+=== "Hypercorn" -```console -$ pip install hypercorn + * Hypercorn, an ASGI server also compatible with HTTP/2. ----> 100% -``` +
-
+ ```console + $ pip install hypercorn + + ---> 100% + ``` -...or any other ASGI server. +
+ + ...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.: -
+=== "Uvicorn" -```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +
-INFO: 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 -
+ INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) + ``` -or with Hypercorn: +
-
+=== "Hypercorn" -```console -$ hypercorn main:app --bind 0.0.0.0:80 +
-Running on 0.0.0.0:8080 over http (CTRL + C to quit) -``` + ```console + $ hypercorn main:app --bind 0.0.0.0:80 -
+ Running on 0.0.0.0:8080 over http (CTRL + C to quit) + ``` + +
You might want to set up some tooling to make sure it is restarted automatically if it stops. diff --git a/docs/en/docs/js/custom.js b/docs/en/docs/js/custom.js index 0f1d48521..72140df8b 100644 --- a/docs/en/docs/js/custom.js +++ b/docs/en/docs/js/custom.js @@ -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"); diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 717dc8e3c..9e13e68c5 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -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 diff --git a/docs/es/mkdocs.yml b/docs/es/mkdocs.yml index 304c01592..e9fe5a3c8 100644 --- a/docs/es/mkdocs.yml +++ b/docs/es/mkdocs.yml @@ -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 diff --git a/docs/pt/mkdocs.yml b/docs/pt/mkdocs.yml index 928754849..70e8dd106 100644 --- a/docs/pt/mkdocs.yml +++ b/docs/pt/mkdocs.yml @@ -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 diff --git a/docs/zh/mkdocs.yml b/docs/zh/mkdocs.yml index 1b7588cbb..6a95e605d 100644 --- a/docs/zh/mkdocs.yml +++ b/docs/zh/mkdocs.yml @@ -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 diff --git a/scripts/docs.py b/scripts/docs.py index 186a3e4f8..73f21371b 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -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():