⬆️ 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

docs/en/docs/advanced/settings.md

@@ -15,6 +15,8 @@ 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:
 
+=== "Linux, macOS, Windows Bash"
+
     <div class="termy">
 
     ```console
@@ -29,7 +31,7 @@ Hello Wade Wilson
 
     </div>
 
-Or in PowerShell in Windows:
+=== "Windows PowerShell"
 
     <div class="termy">
 

docs/en/docs/contributing.md

@@ -24,6 +24,8 @@ That will create a directory `./env/` with the Python binaries and then you will
 
 Activate the new environment with:
 
+=== "Linux, macOS"
+
     <div class="termy">
 
     ```console
@@ -32,7 +34,7 @@ $ source ./env/bin/activate
 
     </div>
 
-Or in Windows' PowerShell:
+=== "Windows PowerShell"
 
     <div class="termy">
 
@@ -42,6 +44,8 @@ $ .\env\Scripts\Activate.ps1
 
     </div>
 
+=== "Windows Bash"
+
     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">
@@ -54,6 +58,8 @@ $ source ./env/Scripts/activate
 
 To check it worked, use:
 
+=== "Linux, macOS, Windows Bash"
+
     <div class="termy">
 
     ```console
@@ -64,9 +70,7 @@ some/directory/fastapi/env/bin/pip
 
     </div>
 
-If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
+=== "Windows PowerShell"
-
-Or in Windows PowerShell:
 
     <div class="termy">
 
@@ -78,6 +82,10 @@ some/directory/fastapi/env/bin/pip
 
     </div>
 
+If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
+
+
+
 !!! tip
     Every time you install a new package with `pip` under that environment, activate the environment again.
 
@@ -103,6 +111,8 @@ 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"
+
     <div class="termy">
 
     ```console
@@ -113,6 +123,8 @@ $ flit install --deps develop --symlink
 
     </div>
 
+=== "Windows"
+
     If you are on Windows, use `--pth-file` instead of `--symlink`:
 
     <div class="termy">

docs/en/docs/deployment.md

@@ -329,6 +329,8 @@ You can deploy **FastAPI** directly without Docker too.
 
 You just need to install an ASGI compatible server like:
 
+=== "Uvicorn"
+
     * <a href="https://www.uvicorn.org/" class="external-link" target="_blank">Uvicorn</a>, a lightning-fast ASGI server, built on uvloop and httptools.
 
     <div class="termy">
@@ -341,6 +343,8 @@ $ pip install uvicorn
 
     </div>
 
+=== "Hypercorn"
+
     * <a href="https://gitlab.com/pgjones/hypercorn" class="external-link" target="_blank">Hypercorn</a>, an ASGI server also compatible with HTTP/2.
 
     <div class="termy">
@@ -357,6 +361,8 @@ $ pip install hypercorn
 
 And run your application the same way you have done in the tutorials, but without the `--reload` option, e.g.:
 
+=== "Uvicorn"
+
     <div class="termy">
 
     ```console
@@ -367,7 +373,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 80
 
     </div>
 
-or with Hypercorn:
+=== "Hypercorn"
 
     <div class="termy">
 

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");

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

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

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

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

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 get_base_lang_config(lang: str):
-def new_lang(lang: str = typer.Argument(..., callback=lang_callback)):
+    en_config = get_en_config()
-    """
-    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"))
     fastapi_url_base = "https://fastapi.tiangolo.com/"
-    new_config = {}
+    new_config = en_config.copy()
-    new_config["site_name"] = en_config["site_name"]
-    new_config["site_description"] = en_config["site_description"]
     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():