From 5b82463a9d84379103d5d1db780c67411cf4026c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Thu, 8 Aug 2024 20:55:55 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=91=B7=20Upgrade=20build=20docs=20configs?= =?UTF-8?q?=20(#914)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/build-docs.yml | 14 +++--- docs/css/termynal.css | 1 + docs/js/custom.js | 4 +- docs/js/termynal.js | 1 - mkdocs.insiders.yml | 6 ++- mkdocs.yml | 84 +++++++++++++++++++++++++------- requirements-docs-insiders.txt | 3 ++ requirements-docs.txt | 13 ++--- scripts/docs.py | 11 ++--- scripts/mkdocs_hooks.py | 38 +++++++++++++++ 10 files changed, 137 insertions(+), 38 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 931e4aed13..a38691714e 100644 --- a/.github/workflows/build-docs.yml +++ b/.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 diff --git a/docs/css/termynal.css b/docs/css/termynal.css index af2fbe6700..8534f91021 100644 --- a/docs/css/termynal.css +++ b/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; } diff --git a/docs/js/custom.js b/docs/js/custom.js index 0dda9fdd54..ef64c612a9 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/js/termynal.js b/docs/js/termynal.js index 4ac32708a3..45bb371c83 100644 --- a/docs/js/termynal.js +++ b/docs/js/termynal.js @@ -249,7 +249,6 @@ class Termynal { attrs += `${this.pfx}-${prop}="${line[prop]}" ` } } - return attrs; } } diff --git a/mkdocs.insiders.yml b/mkdocs.insiders.yml index d24d754930..c1568000e2 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 2efe674049..707c9a52f7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,16 +26,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.svg @@ -43,9 +55,11 @@ theme: 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,29 +135,49 @@ 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 @@ -151,6 +185,19 @@ 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 diff --git a/requirements-docs-insiders.txt b/requirements-docs-insiders.txt new file mode 100644 index 0000000000..d8d3c37a9f --- /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 13a1df0540..4ad8149417 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1,8 +1,7 @@ -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 @@ -10,8 +9,10 @@ pyyaml >=5.3.1,<7.0.0 # 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 diff --git a/scripts/docs.py b/scripts/docs.py index b91a10eb73..3a3ef7f062 100644 --- a/scripts/docs.py +++ b/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() diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py new file mode 100644 index 0000000000..f09e9a99df --- /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)