👷 Upgrade build docs configs (#914)

Author: tiangolo

.github/workflows/build-docs.yml

@@ -18,7 +18,7 @@ jobs:
       docs: ${{ steps.filter.outputs.docs }}
     steps:
     - uses: actions/checkout@v4
-    # For pull requests it's not necessary to checkout the code but for master it is
+    # For pull requests it's not necessary to checkout the code but for the main branch it is
     - uses: dorny/paths-filter@v3
       id: filter
       with:
@@ -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') }}-v02
+          key: ${{ runner.os }}-python-docs-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml', 'requirements-docs.txt', 'requirements-docs-insiders.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.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
-          pip install git+https://${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
+        run: pip install -r requirements-docs-insiders.txt
+        env:
+          TOKEN: ${{ secrets.TYPER_MKDOCS_MATERIAL_INSIDERS }}
       - uses: actions/cache@v4
         with:
           key: mkdocs-cards-${{ github.ref }}-v1

docs/css/termynal.css

@@ -26,6 +26,7 @@
     position: relative;
     -webkit-box-sizing: border-box;
             box-sizing: border-box;
+    /* Custom line-height */
     line-height: 1.2;
 }
 

docs/js/custom.js

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

docs/js/termynal.js

@@ -249,7 +249,6 @@ class Termynal {
                 attrs += `${this.pfx}-${prop}="${line[prop]}" `
             }
         }
-
         return attrs;
     }
 }

mkdocs.insiders.yml

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

mkdocs.yml

@@ -26,26 +26,40 @@ 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.svg
   favicon: img/favicon.png
   language: en
 repo_name: tiangolo/typer
 repo_url: https://github.com/tiangolo/typer
-edit_uri: ""
 plugins:
-  search: null
+  # Material for MkDocs
+  search:
+  social:
+  # Other plugins
   redirects:
     redirect_maps:
       typer-cli.md: tutorial/typer-command.md
@@ -121,36 +135,69 @@ nav:
   - release-notes.md
 
 markdown_extensions:
+  # Python Markdown
+  abbr:
+  attr_list:
+  footnotes:
+  md_in_html:
+  tables:
   toc:
     permalink: true
-  markdown.extensions.attr_list:
-  markdown.extensions.tables:
-  markdown.extensions.md_in_html:
 
+  # 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
-    - check
+    # Custom types
+    - info
+  pymdownx.blocks.details:
   pymdownx.blocks.tab:
     alternate_style: True
+
+  # Other extensions
   mdx_include:
     base_path: docs
 
 extra:
   analytics:
     provider: google
     property: G-T78C5GNRXK
+    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/typer
@@ -172,3 +219,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,17 +1,18 @@
 -e .
 
-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
 # For image processing by Material for MkDocs
 pillow==10.3.0
 # For image processing by Material for MkDocs
-cairosvg==2.7.0
-mkdocstrings[python]==0.23.0
-griffe-typingdoc==0.2.2
+cairosvg==2.7.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
-black==24.3.0
+# black==24.3.0
+mkdocs-macros-plugin==1.0.5

scripts/docs.py

@@ -7,10 +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
 
 logging.basicConfig(level=logging.INFO)
@@ -93,8 +89,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)