⬆️ 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
5 years ago · 483bce3ae1
9 changed files with 184 additions and 144 deletions
--- a/docs/en/docs/advanced/settings.md
+++ b/docs/en/docs/advanced/settings.md
@ -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

--- 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:

-<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
+    ```

-If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉
+    </div>

-Or in Windows PowerShell:
+=== "Windows PowerShell"

-<div class="termy">
+    <div class="termy">

-```console
-$ Get-Command pip
+    ```console
+    $ Get-Command pip
+
+    some/directory/fastapi/env/bin/pip
+    ```
+
+    </div>
+
+If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉

-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.

--- 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:

-* <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
+
+    ---> 100%
+    ```

-...or any other ASGI server.
+    </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.

--- 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");
--- 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
--- 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/[email protected]/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
--- 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
--- 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
--- 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():