🔧 Upgrade Material for MkDocs and remove insiders (#14375)

diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
index f78b6730eec8a043704ea2abb74485e2da38df5a..995a0eb419b91ecc5cdddf1a1255bf6a5c4a36e5 100644 (file)
--- a/.github/workflows/build-docs.yml
+++ b/.github/workflows/build-docs.yml
@@ -32,12 +32,9 @@ jobs:
             - docs/**
             - docs_src/**
             - requirements-docs.txt
-            - requirements-docs-insiders.txt
             - pyproject.toml
             - mkdocs.yml
-            - mkdocs.insiders.yml
-            - mkdocs.maybe-insiders.yml
-            - mkdocs.no-insiders.yml
+            - mkdocs.env.yml
             - .github/workflows/build-docs.yml
             - .github/workflows/deploy-docs.yml
             - scripts/mkdocs_hooks.py
@@ -63,12 +60,6 @@ jobs:
             pyproject.toml
       - name: Install docs extras
         run: uv pip install -r requirements-docs.txt
-      # Install MkDocs Material Insiders here just to put it in the cache for the rest of the steps
-      - name: Install Material for MkDocs Insiders
-        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' )
-        run: uv pip install -r requirements-docs-insiders.txt
-        env:
-          TOKEN: ${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}
       - name: Verify Docs
         run: python ./scripts/docs.py verify-docs
       - name: Export Language Codes
@@ -105,11 +96,6 @@ jobs:
             pyproject.toml
       - name: Install docs extras
         run: uv pip install -r requirements-docs.txt
-      - name: Install Material for MkDocs Insiders
-        if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' )
-        run: uv pip install -r requirements-docs-insiders.txt
-        env:
-          TOKEN: ${{ secrets.FASTAPI_MKDOCS_MATERIAL_INSIDERS }}
       - name: Update Languages
         run: python ./scripts/docs.py update-languages
       - uses: actions/cache@v4

diff --git a/docs/en/mkdocs.maybe-insiders.yml b/docs/en/mkdocs.env.yml
similarity index 78%
rename from docs/en/mkdocs.maybe-insiders.yml
rename to docs/en/mkdocs.env.yml
index 37fd9338efc5f273e3e63d859e85b299d62e89e1..c5f6e07d799ee0914133d81e5ba4a4473b7f7e3f 100644 (file)
--- a/docs/en/mkdocs.maybe-insiders.yml
+++ b/docs/en/mkdocs.env.yml
@@ -1,6 +1,5 @@
 # Define this here and not in the main mkdocs.yml file because that one is auto
 # updated and written, and the script would remove the env var
-INHERIT: !ENV [INSIDERS_FILE, '../en/mkdocs.no-insiders.yml']
 markdown_extensions:
   pymdownx.highlight:
     linenums: !ENV [LINENUMS, false]

diff --git a/docs/en/mkdocs.insiders.yml b/docs/en/mkdocs.insiders.yml
deleted file mode 100644 (file)
index 8d6d26e..0000000
--- a/docs/en/mkdocs.insiders.yml
+++ /dev/null
@@ -1,10 +0,0 @@
-plugins:
-  social:
-    cards_layout_options:
-      logo: ../en/docs/img/icon-white.svg
-  typeset:
-markdown_extensions:
-  material.extensions.preview:
-    targets:
-      include:
-        - "*"

diff --git a/docs/en/mkdocs.no-insiders.yml b/docs/en/mkdocs.no-insiders.yml
deleted file mode 100644 (file)
index e69de29..0000000

diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml
index df47c6f9c1e7f46434a80b36b6a57660bf9bd1c3..8be832f117bea20667b2c9601cec662271d6faf5 100644 (file)
--- a/docs/en/mkdocs.yml
+++ b/docs/en/mkdocs.yml
@@ -1,4 +1,4 @@
-INHERIT: ../en/mkdocs.maybe-insiders.yml
+INHERIT: ../en/mkdocs.env.yml
 site_name: FastAPI
 site_description: FastAPI framework, high performance, easy to learn, fast to code, ready for production
 site_url: https://fastapi.tiangolo.com/
@@ -52,6 +52,10 @@ theme:
 repo_name: fastapi/fastapi
 repo_url: https://github.com/fastapi/fastapi
 plugins:
+  social:
+    cards_layout_options:
+      logo: ../en/docs/img/icon-white.svg
+  typeset:
   search: null
   macros:
     include_yaml:
@@ -253,6 +257,10 @@ nav:
   - management.md
 - release-notes.md
 markdown_extensions:
+  material.extensions.preview:
+    targets:
+      include:
+        - "*"
   abbr: null
   attr_list: null
   footnotes: null

diff --git a/requirements-docs-insiders.txt b/requirements-docs-insiders.txt
deleted file mode 100644 (file)
index d8d3c37..0000000
--- a/requirements-docs-insiders.txt
+++ /dev/null
@@ -1,3 +0,0 @@
-git+https://${TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.5.30-insiders-4.53.11
-git+https://${TOKEN}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
-git+https://${TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git

diff --git a/requirements-docs.txt b/requirements-docs.txt
index 696eb2a334ca8e26c847f44192c8f96b0179fbf0..d60125bbe5f48e7444be96292c44a4825c3582b4 100644 (file)
--- a/requirements-docs.txt
+++ b/requirements-docs.txt
@@ -1,6 +1,6 @@
 -e .
 -r requirements-docs-tests.txt
-mkdocs-material==9.6.16
+mkdocs-material==9.7.0
 mdx-include >=1.4.1,<2.0.0
 mkdocs-redirects>=1.2.1,<1.3.0
 typer == 0.16.0
@@ -13,6 +13,7 @@ pillow==11.3.0
 cairosvg==2.8.2
 mkdocstrings[python]==0.30.1
 griffe-typingdoc==0.3.0
+griffe-warnings-deprecated==1.1.0
 # For griffe, it formats with black
 black==25.1.0
 mkdocs-macros-plugin==1.4.1

diff --git a/scripts/docs.py b/scripts/docs.py
index 1a336a03642045f73d93be3d8a349dc4088b840f..d08a218f8b85f50880badf69e1ee23c03c50ae52 100644 (file)
--- a/scripts/docs.py
+++ b/scripts/docs.py
@@ -4,9 +4,7 @@ import os
 import re
 import shutil
 import subprocess
-from functools import lru_cache
 from http.server import HTTPServer, SimpleHTTPRequestHandler
-from importlib import metadata
 from multiprocessing import Pool
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
@@ -47,12 +45,6 @@ build_site_path = Path("site_build").absolute()
 header_with_permalink_pattern = re.compile(r"^(#{1,6}) (.+?)(\s*\{\s*#.*\s*\})\s*$")
 
 
-@lru_cache
-def is_mkdocs_insiders() -> bool:
-    version = metadata.version("mkdocs-material")
-    return "insiders" in version
-
-
 def get_en_config() -> Dict[str, Any]:
     return mkdocs.utils.yaml_load(en_config_path.read_text(encoding="utf-8"))
 
@@ -77,9 +69,7 @@ def complete_existing_lang(incomplete: str):
 
 @app.callback()
 def callback() -> None:
-    if is_mkdocs_insiders():
-        os.environ["INSIDERS_FILE"] = "../en/mkdocs.insiders.yml"
-    # For MacOS with insiders and Cairo
+    # For MacOS with Cairo
     os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib"
 
 
@@ -115,10 +105,6 @@ def build_lang(
     """
     Build the docs for a language.
     """
-    insiders_env_file = os.environ.get("INSIDERS_FILE")
-    print(f"Insiders file {insiders_env_file}")
-    if is_mkdocs_insiders():
-        print("Using insiders")
     lang_path: Path = Path("docs") / lang
     if not lang_path.is_dir():
         typer.echo(f"The language translation doesn't seem to exist yet: {lang}")