👷 Upgrade build docs configs

.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
 
@@ -49,30 +52,27 @@ jobs:
  uses: actions/setup-python@v5
  with:
  python-version: "3.11"
- - uses: actions/cache@v3
+ - uses: actions/cache@v4
  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') }}-v01
  - 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.ASYNCER_MKDOCS_MATERIAL_INSIDERS }}@github.com/squidfunk/mkdocs-material-insiders.git
- pip install git+https://${{ secrets.ASYNCER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/griffe-typing-deprecated.git
- pip install git+https://${{ secrets.ASYNCER_MKDOCS_MATERIAL_INSIDERS }}@github.com/pawamoy-insiders/mkdocstrings-python.git
- - uses: actions/cache@v3
+ run: pip install -r requirements-docs-insiders.txt
+ env:
+ TOKEN: ${{ secrets.ASYNCER_MKDOCS_MATERIAL_INSIDERS }}
+ - uses: actions/cache@v4
  with:
  key: mkdocs-cards-${{ github.ref }}
  path: .cache
+ - name: Verify README
+ run: python ./scripts/docs.py verify-readme
  - name: Build Docs
- if: github.event_name == 'pull_request' && github.secret_source != 'Actions'
- run: python -m mkdocs build
- - name: Build Docs with Insiders
- if: github.event_name != 'pull_request' || github.secret_source == 'Actions'
- run: python -m mkdocs build --config-file mkdocs.insiders.yml
+ run: python ./scripts/docs.py build
  - uses: actions/upload-artifact@v4
  with:
  name: docs-site

docs/help.md

@@ -163,12 +163,15 @@ And if there's any other style or consistency need, I'll ask directly for that,
 
 * Then **comment** saying that you did that, that's how I will know you really checked it.
 
-!!! info
- Unfortunately, I can't simply trust PRs that just have several approvals.
+/// info
 
- Several times it has happened that there are PRs with 3, 5 or more approvals, probably because the description is appealing, but when I check the PRs, they are actually broken, have a bug, or don't solve the problem they claim to solve. 😅
+Unfortunately, I can't simply trust PRs that just have several approvals.
 
- So, it's really important that you actually read and run the code, and let me know in the comments that you did. 🤓
+Several times it has happened that there are PRs with 3, 5 or more approvals, probably because the description is appealing, but when I check the PRs, they are actually broken, have a bug, or don't solve the problem they claim to solve. 😅
+
+So, it's really important that you actually read and run the code, and let me know in the comments that you did. 🤓
+
+///
 
 * If the PR can be simplified in a way, you can ask for that, but there's no need to be too picky, there might be a lot of subjective points of view (and I will have my own as well 🙈), so it's better if you can focus on the fundamental things.
 
@@ -215,10 +218,13 @@ If you can help me with that, **you are helping me maintain Asyncer** and making
 
 Join the 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">FastAPI and Friends Discord chat server</a> 👥 and hang out with others in the community. There's an `#asyncer` channel.
 
-!!! tip
- For questions, ask them in <a href="https://github.com/tiangolo/asyncer/discussions/new?category=questions" class="external-link" target="_blank">GitHub Discussions</a>, there's a much better chance you will receive help there.
+/// tip
+
+For questions, ask them in <a href="https://github.com/tiangolo/asyncer/discussions/new?category=questions" class="external-link" target="_blank">GitHub Discussions</a>, there's a much better chance you will receive help there.
+
+Use the chat only for other general conversations.
 
- Use the chat only for other general conversations.
+///
 
 ### Don't use the chat for questions
 

docs/index.md

@@ -1,3 +1,7 @@
+<style>
+.md-content .md-typeset h1 { display: none; }
+</style>
+
 <p align="center">
  <a href="https://asyncer.tiangolo.com"><img src="https://asyncer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" alt="Asyncer"></a>
 </p>

docs/js/custom.js

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

docs/tutorial/soonify-return.md

@@ -203,5 +203,8 @@ The **2 seconds** is more than what the function will take to finish because it
 
 We verify that first, checking that `soon_value1.ready` is `True`, and then we can safely print the value.
 
-!!! tip
- If you feel like you need to **access** values **generated** by the async functions **inside** the same `async with` block for a **task group**, you might need to use a different approach, for example, with <a href="https://anyio.readthedocs.io/en/stable/streams.html" class="external-link" target="_blank">AnyIO Streams</a>.
+/// tip
+
+If you feel like you need to **access** values **generated** by the async functions **inside** the same `async with` block for a **task group**, you might need to use a different approach, for example, with <a href="https://anyio.readthedocs.io/en/stable/streams.html" class="external-link" target="_blank">AnyIO Streams</a>.
+
+///

mkdocs.insiders.yml

@@ -1,4 +1,7 @@
-INHERIT: mkdocs.yml
 plugins:
- - search
- - social
+ typeset:
+markdown_extensions:
+ material.extensions.preview:
+ targets:
+ include:
+ - ./*

mkdocs.maybe-insiders.yml

@@ -0,0 +1,6 @@
+# Define this here and not in the main mkdocs.yml file because that one could be auto
+# updated and written, and the script would remove the env var
+INHERIT: !ENV [INSIDERS_FILE, './mkdocs.no-insiders.yml']
+markdown_extensions:
+ pymdownx.highlight:
+ linenums: !ENV [LINENUMS, false]

mkdocs.yml

@@ -1,3 +1,4 @@
+INHERIT: ./mkdocs.maybe-insiders.yml
 site_name: Asyncer
 site_description: Asyncer, async and await, focused on developer experience.
 site_url: https://asyncer.tiangolo.com/
@@ -23,24 +24,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-white.svg
  favicon: img/favicon.png
  language: en
 repo_name: tiangolo/asyncer
 repo_url: https://github.com/tiangolo/asyncer
-edit_uri: ''
+plugins:
+ # Material for MkDocs
+ search:
+ social:
+
 nav:
  - Asyncer: index.md
  - Tutorial - User Guide:
@@ -54,27 +71,70 @@ nav:
  - tutorial/syncify-no-raise.md
  - help.md
  - release-notes.md
+
 markdown_extensions:
-- toc:
+ # Python Markdown
+ abbr:
+ attr_list:
+ footnotes:
+ md_in_html:
+ tables:
+ toc:
  permalink: true
-- markdown.extensions.codehilite:
- guess_lang: false
-- admonition
-- codehilite
-- extra
-- pymdownx.superfences:
+
+ # 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.tabbed:
- alternate_style: true
-- mdx_include
+ format: !!python/name:pymdownx.superfences.fence_code_format
+ pymdownx.tilde:
+
+ # pymdownx blocks
+ pymdownx.blocks.admonition:
+ types:
+ - note
+ - attention
+ - caution
+ - danger
+ - error
+ - tip
+ - hint
+ - warning
+ # Custom types
+ - info
+ pymdownx.blocks.details:
+ pymdownx.blocks.tab:
+ alternate_style: True
+
+ # Other extensions
+ mdx_include:
 
 extra:
  analytics:
  provider: google
  property: G-T4CRRCXTNY
+ 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/asyncer
@@ -96,3 +156,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/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

requirements-docs.txt

@@ -1,17 +1,18 @@
 -e .
 
-mkdocs-material==9.5.24
+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.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==23.3.0
+typer == 0.12.3
+mkdocs-macros-plugin==1.0.5