From 970492487aa4f9fa8cfa4f381b094891f87b6a1f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Thu, 8 Aug 2024 19:13:10 -0500 Subject: [PATCH] =?utf8?q?=F0=9F=91=B7=20Upgrade=20build=20docs=20configs?= =?utf8?q?=20(#1047)?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .github/workflows/build-docs.yml | 12 +++-- docs/js/custom.js | 4 +- docs/tutorial/index.md | 2 + mkdocs.insiders.yml | 6 ++- mkdocs.yml | 89 +++++++++++++++++++++++++------- requirements-docs-insiders.txt | 3 ++ requirements-docs.txt | 10 ++-- scripts/docs.py | 17 ++++-- scripts/mkdocs_hooks.py | 38 ++++++++++++++ 9 files changed, 146 insertions(+), 35 deletions(-) create mode 100644 requirements-docs-insiders.txt create mode 100644 scripts/mkdocs_hooks.py diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index d4bb6cf6..a2393052 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 @@ -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 }} diff --git a/docs/js/custom.js b/docs/js/custom.js index 0dda9fdd..ef64c612 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/index.md b/docs/tutorial/index.md index 88d952a7..3972fc47 100644 --- a/docs/tutorial/index.md +++ b/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 FastAPI's Python types intro. diff --git a/mkdocs.insiders.yml b/mkdocs.insiders.yml index d24d7549..c1568000 100644 --- a/mkdocs.insiders.yml +++ b/mkdocs.insiders.yml @@ -1,3 +1,7 @@ plugins: - social: typeset: +markdown_extensions: + material.extensions.preview: + targets: + include: + - ./* diff --git a/mkdocs.yml b/mkdocs.yml index 1bf71d7d..df492f02 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,16 +25,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 @@ -42,11 +54,14 @@ theme: 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 diff --git a/requirements-docs-insiders.txt b/requirements-docs-insiders.txt new file mode 100644 index 00000000..d8d3c37a --- /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 f30c2457..3c00f0a2 100644 --- a/requirements-docs.txt +++ b/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 diff --git a/scripts/docs.py b/scripts/docs.py index cab6c87d..8efcdda5 100644 --- a/scripts/docs.py +++ b/scripts/docs.py @@ -7,9 +7,6 @@ from http.server import HTTPServer, SimpleHTTPRequestHandler 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 and + new_content = re.sub( + r".*?", + "", + 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() diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py new file mode 100644 index 00000000..f09e9a99 --- /dev/null +++ b/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) -- 2.47.2