👷 Upgrade build docs configs (#1047)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/build-docs.yml

@@ -28,9 +28,12 @@ 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
             - .github/workflows/build-docs.yml
             - .github/workflows/deploy-docs.yml
 
@@ -53,16 +56,15 @@ jobs:
         id: cache
         with:
           path: ${{ env.pythonLocation }}
-          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt') }}-v01
+          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-insiders.txt', 'requirements-docs-tests.txt') }}-v02
       - name: Install docs extras
         if: steps.cache.outputs.cache-hit != 'true'
         run: pip install -r requirements-docs.txt
       - name: Install Material for MkDocs Insiders
         if: ( github.event_name != 'pull_request' || github.secret_source == 'Actions' ) && steps.cache.outputs.cache-hit != 'true'
-        run: |
-          pip install git+https://${{ secrets.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
-          pip install git+https://${{ secrets.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
-          pip install git+https://${{ secrets.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
+        run: pip install -r requirements-docs-insiders.txt
+        env:
+          TOKEN: ${{ secrets.SQLMODEL_MKDOCS_MATERIAL_INSIDERS }}
       - uses: actions/cache@v4
         with:
           key: mkdocs-cards-${{ github.ref }}

docs/js/custom.js

@@ -110,4 +110,6 @@ async function main() {
     setupTermynal()
 }
 
-main()
+document$.subscribe(() => {
+    main()
+})

docs/tutorial/index.md

@@ -1,5 +1,7 @@
 # Intro, Installation, and First Steps
 
+Before we start playing with **SQLModel**, let's prepare everything else we need. A bit of type annotations, setting up the environment to install everything, and installing DB Browser for SQLite. 🤓
+
 ## Type hints
 
 If you need a refresher about how to use Python type hints (type annotations), check <a href="https://fastapi.tiangolo.com/python-types/" class="external-link" target="_blank">FastAPI's Python types intro</a>.

mkdocs.insiders.yml

@@ -1,3 +1,7 @@
 plugins:
-  social:
   typeset:
+markdown_extensions:
+  material.extensions.preview:
+    targets:
+      include:
+        - ./*

mkdocs.yml

@@ -25,28 +25,43 @@ theme:
       icon: material/lightbulb-outline
       name: Switch to system preference
   features:
-  - search.suggest
-  - search.highlight
+  - content.code.annotate
+  - content.code.copy
+  # - content.code.select
+  - content.footnote.tooltips
   - content.tabs.link
-  - navigation.indexes
   - content.tooltips
+  - navigation.footer
+  - navigation.indexes
+  - navigation.instant
+  - navigation.instant.prefetch
+  - navigation.instant.preview
+  - navigation.instant.progress
   - navigation.path
-  - content.code.annotate
-  - content.code.copy
-  - content.code.select
   # - navigation.tabs
+  # - navigation.tabs.sticky
+  - navigation.top
+  - navigation.tracking
+  - search.highlight
+  - search.share
+  - search.suggest
+  - toc.follow
+
   icon:
     repo: fontawesome/brands/github-alt
   logo: img/icon-white.svg
   favicon: img/favicon.png
   language: en
 repo_name: tiangolo/sqlmodel
 repo_url: https://github.com/tiangolo/sqlmodel
-edit_uri: ''
 plugins:
-  search: null
-  markdownextradata:
-    data: ./data
+  # Material for MkDocs
+  search:
+  social:
+  # Other plugins
+  macros:
+    include_yaml:
+    - sponsors: data/sponsors.yml
 
 nav:
   - SQLModel: index.md
@@ -113,33 +128,68 @@ nav:
   - release-notes.md
 
 markdown_extensions:
-  markdown.extensions.attr_list:
-  markdown.extensions.tables:
-  markdown.extensions.md_in_html:
+  # Python Markdown
+  abbr:
+  attr_list:
+  footnotes:
+  md_in_html:
+  tables:
   toc:
     permalink: true
+
+  # Python Markdown Extensions
+  pymdownx.betterem:
+    smart_enable: all
+  pymdownx.caret:
+  pymdownx.highlight:
+    line_spans: __span
+  pymdownx.inlinehilite:
+  pymdownx.keys:
+  pymdownx.mark:
   pymdownx.superfences:
     custom_fences:
     - name: mermaid
       class: mermaid
-      format: !!python/name:pymdownx.superfences.fence_code_format ''
-  pymdownx.betterem:
-  pymdownx.blocks.details:
+      format: !!python/name:pymdownx.superfences.fence_code_format
+  pymdownx.tilde:
+
+  # pymdownx blocks
   pymdownx.blocks.admonition:
     types:
     - note
-    - info
+    - attention
+    - caution
+    - danger
+    - error
     - tip
+    - hint
     - warning
-    - danger
+    # Custom types
+    - info
+  pymdownx.blocks.details:
   pymdownx.blocks.tab:
     alternate_style: True
+
+  # Other extensions
   mdx_include:
 
 extra:
   analytics:
     provider: google
     property: G-J8HVTT936W
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: >-
+            Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: >-
+            Thanks for your feedback!
   social:
   - icon: fontawesome/brands/github-alt
     link: https://github.com/tiangolo/sqlmodel
@@ -161,3 +211,6 @@ extra_css:
 extra_javascript:
   - js/termynal.js
   - js/custom.js
+
+hooks:
+  - scripts/mkdocs_hooks.py

requirements-docs-insiders.txt

@@ -0,0 +1,3 @@
+git+https://${TOKEN}@github.com/squidfunk/[email protected]
+git+https://${TOKEN}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
+git+https://${TOKEN}@github.com/pawamoy-insiders/mkdocstrings-python.git

requirements-docs.txt

@@ -1,18 +1,18 @@
 -e .
 -r requirements-docs-tests.txt
-mkdocs-material==9.4.7
+mkdocs-material==9.5.18
 mdx-include >=1.4.1,<2.0.0
-mkdocs-markdownextradata-plugin >=0.1.7,<0.3.0
 mkdocs-redirects>=1.2.1,<1.3.0
 pyyaml >=5.3.1,<7.0.0
 # For Material for MkDocs, Chinese search
-jieba==0.42.1
+# jieba==0.42.1
 # For image processing by Material for MkDocs
-pillow==10.1.0
+pillow==10.3.0
 # For image processing by Material for MkDocs
 cairosvg==2.7.1
-mkdocstrings[python]==0.25.1
+# mkdocstrings[python]==0.25.1
 # Enable griffe-typingdoc once dropping Python 3.7 and upgrading typing-extensions
 # griffe-typingdoc==0.2.5
 # For griffe, it formats with black
 typer == 0.12.3
+mkdocs-macros-plugin==1.0.5

scripts/docs.py

@@ -7,9 +7,6 @@
 from importlib import metadata
 from pathlib import Path
 
-import mkdocs.commands.build
-import mkdocs.commands.serve
-import mkdocs.config
 import mkdocs.utils
 import typer
 from jinja2 import Template
@@ -68,6 +65,13 @@ def generate_readme_content() -> str:
     pre_content = content[frontmatter_end:pre_end]
     post_content = content[post_start:]
     new_content = pre_content + message + post_content
+    # Remove content between <!-- only-mkdocs --> and <!-- /only-mkdocs -->
+    new_content = re.sub(
+        r"<!-- only-mkdocs -->.*?<!-- /only-mkdocs -->",
+        "",
+        new_content,
+        flags=re.DOTALL,
+    )
     return new_content
 
 
@@ -111,8 +115,11 @@ def live() -> None:
     en.
     """
     # Enable line numbers during local development to make it easier to highlight
-    os.environ["LINENUMS"] = "true"
-    mkdocs.commands.serve.serve(dev_addr="127.0.0.1:8008")
+    subprocess.run(
+        ["mkdocs", "serve", "--dev-addr", "127.0.0.1:8008", "--dirty"],
+        env={**os.environ, "LINENUMS": "true"},
+        check=True,
+    )
 
 
 @app.command()

scripts/mkdocs_hooks.py

@@ -0,0 +1,38 @@
+from typing import Any, List, Union
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import Files
+from mkdocs.structure.nav import Link, Navigation, Section
+from mkdocs.structure.pages import Page
+
+
+def generate_renamed_section_items(
+    items: List[Union[Page, Section, Link]], *, config: MkDocsConfig
+) -> List[Union[Page, Section, Link]]:
+    new_items: List[Union[Page, Section, Link]] = []
+    for item in items:
+        if isinstance(item, Section):
+            new_title = item.title
+            new_children = generate_renamed_section_items(item.children, config=config)
+            first_child = new_children[0]
+            if isinstance(first_child, Page):
+                if first_child.file.src_path.endswith("index.md"):
+                    # Read the source so that the title is parsed and available
+                    first_child.read_source(config=config)
+                    new_title = first_child.title or new_title
+            # Creating a new section makes it render it collapsed by default
+            # no idea why, so, let's just modify the existing one
+            # new_section = Section(title=new_title, children=new_children)
+            item.title = new_title
+            item.children = new_children
+            new_items.append(item)
+        else:
+            new_items.append(item)
+    return new_items
+
+
+def on_nav(
+    nav: Navigation, *, config: MkDocsConfig, files: Files, **kwargs: Any
+) -> Navigation:
+    new_items = generate_renamed_section_items(nav.items, config=config)
+    return Navigation(items=new_items, pages=nav.pages)