diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 2e18483..5cedd60 100644 --- a/.github/workflows/build-docs.yml +++ b/.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 diff --git a/docs/help.md b/docs/help.md index fc8202d..cea3ac5 100644 --- a/docs/help.md +++ b/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 👥 FastAPI and Friends Discord chat server 👥 and hang out with others in the community. There's an `#asyncer` channel. -!!! tip - For questions, ask them in GitHub Discussions, there's a much better chance you will receive help there. +/// tip + +For questions, ask them in GitHub Discussions, 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 diff --git a/docs/index.md b/docs/index.md index a3cc651..4970472 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,7 @@ + +

Asyncer

diff --git a/docs/js/custom.js b/docs/js/custom.js index 0dda9fd..ef64c61 100644 --- a/docs/js/custom.js +++ b/docs/js/custom.js @@ -110,4 +110,6 @@ async function main() { setupTermynal() } -main() +document$.subscribe(() => { + main() +}) diff --git a/docs/tutorial/soonify-return.md b/docs/tutorial/soonify-return.md index 7bccaa3..6ffb378 100644 --- a/docs/tutorial/soonify-return.md +++ b/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 AnyIO Streams. +/// 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 AnyIO Streams. + +/// diff --git a/mkdocs.insiders.yml b/mkdocs.insiders.yml index 9f2775f..c156800 100644 --- a/mkdocs.insiders.yml +++ b/mkdocs.insiders.yml @@ -1,4 +1,7 @@ -INHERIT: mkdocs.yml plugins: - - search - - social + typeset: +markdown_extensions: + material.extensions.preview: + targets: + include: + - ./* diff --git a/mkdocs.maybe-insiders.yml b/mkdocs.maybe-insiders.yml new file mode 100644 index 0000000..07aefaa --- /dev/null +++ b/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] diff --git a/mkdocs.no-insiders.yml b/mkdocs.no-insiders.yml new file mode 100644 index 0000000..e69de29 diff --git a/mkdocs.yml b/mkdocs.yml index a8c7b40..26e8675 100644 --- a/mkdocs.yml +++ b/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,16 +24,28 @@ 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 @@ -40,7 +53,11 @@ theme: 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 diff --git a/requirements-docs-insiders.txt b/requirements-docs-insiders.txt new file mode 100644 index 0000000..d8d3c37 --- /dev/null +++ b/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 diff --git a/requirements-docs.txt b/requirements-docs.txt index af9ba8d..bd83d45 100644 --- a/requirements-docs.txt +++ b/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 diff --git a/scripts/docs.py b/scripts/docs.py new file mode 100644 index 0000000..3a3ef7f --- /dev/null +++ b/scripts/docs.py @@ -0,0 +1,136 @@ +import logging +import os +import re +import subprocess +from functools import lru_cache +from http.server import HTTPServer, SimpleHTTPRequestHandler +from importlib import metadata +from pathlib import Path + +import typer + +logging.basicConfig(level=logging.INFO) + +mkdocs_name = "mkdocs.yml" +en_docs_path = Path("") + +app = typer.Typer() + + +@lru_cache +def is_mkdocs_insiders() -> bool: + version = metadata.version("mkdocs-material") + return "insiders" in version + + +@app.callback() +def callback() -> None: + if is_mkdocs_insiders(): + os.environ["INSIDERS_FILE"] = "./mkdocs.insiders.yml" + # For MacOS with insiders and Cairo + os.environ["DYLD_FALLBACK_LIBRARY_PATH"] = "/opt/homebrew/lib" + + +def generate_readme_content() -> str: + en_index = en_docs_path / "docs" / "index.md" + content = en_index.read_text("utf-8") + match_pre = re.search(r"\n\n", content) + if not match_pre: + raise RuntimeError("Couldn't find pre section (