pydeck 文档生成管线从示例脚本到 Sphinx 文档画廊的三层自动化流程【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl本文以 bindings/pydeck/docs/scripts/README.md 为核心系统讲解 pydeck 官方文档站中“示例画廊”的自动化生成机制embed_examples.py如何把示例脚本转成内嵌源码与交互画面的 .rst 页面、generate_grid_html.py如何聚合生成画廊落地页、snap_thumbnails.py如何为每个示例截取缩略图。读完本文你可以独立复现整套文档构建流程并按 README 给出的标准步骤把一个新的示例图层加入 pydeck 画廊。1. 管线概览三层脚本与目录约定bindings/pydeck/docs/scripts/README.md 开篇即点明定位这是一个“为生成 pydeck 文档服务的辅助脚本集”。整套管线由三个阶段组成每个阶段对应一个脚本阶段脚本产物1. 页面嵌入embed_examples.py一组 .rst 文件每个文件同时内嵌示例源码与可交互的 HTML 实例点击画廊单元格后看到的页面2. 画廊网格generate_grid_html.pygrid.html以缩略图为单元、按分组组织的链接网格即 pydeck 文档站的落地页3. 缩略图snap_thumbnails.py画廊中使用的 .png 缩略图从示例的实际渲染结果截图生成目录约定集中定义在 const.py理解它是理解整条管线的前提EXAMPLES_DIRpydeck 示例目录 bindings/pydeck/examplesL7EXAMPLE_GLOB递归收集examples/下含子目录的全部*.py示例文件L13。子目录会成为画廊上的分组标签而网格、页面、缩略图的命名仍以每个文件的基本名为键因此按子文件夹组织示例只影响分组、不破坏命名体系L9-L12 的注释说明了这一设计GALLERY_DIR画廊 .rst 页面目录docs/gallery/L50HTML_DIR画廊 HTML 文件目录docs/gallery/html/L52LOCAL_IMAGE_DIR缩略图目录docs/gallery/images/L54DECKGL_URL_BASEdeck.gl API 参考文档基址用于给图层示例页挂回链L58。此外const.py 还定义了网格分组逻辑DEFAULT_GROUP Layers表示直接放在examples/根下的示例归入 “Layers” 分组GROUP_ORDER [Layers, Extensions]固定前两个分区的顺序其余分组按字母序排列。grouped_examples()据此返回有序(section_label, [snake_case 名称])列表——例如仓库中的 extensions 子目录含 8 个扩展示例与 post_processing 子目录19 个示例就各自形成独立分区。还有一处 README 未提及但同样重要的环节update_images_rst.py 会基于EXAMPLE_NAMES重新渲染 docs/images.rst。该文件头部注释表明其职责是“把示例缩略图注册进_static目录并把示例页面登记进一个隐藏 toctree”——这正是 Sphinx 能收录gallery/images/*.png与gallery/*.rst的依据当前仓库中的 images.rst 即为该脚本的产物含a5_layer、arc_layer、binary_transport等条目的.. image::注册与.. toctree::列表。2. 第一阶段embed_examples.py——示例脚本到 .rst 页面embed_examples.py 的模块 docstring 说明了它的作用“这些文件就是你在 pydeck 画廊页点击某个网格单元格后看到的页面”。核心函数create_rst()L18-L47对每个示例文件做四件事命名规范化to_snake_case_string()去掉路径与扩展名得到 snake_case 资产名utils.py L13-L15若名称中含layer则拼出 deck.gl 文档回链L21-L25。源码注释坦承这一判断“相当粗糙”后续计划扩展以支持 views 等对象——因此回链只对图层示例生效运行示例并归档 HTML通过subprocess执行python {示例文件}; mv {html} {HTML_DIR}L29-L34。示例脚本本身在顶层目录生成同名.htmldeck 前端由 Jupyter widget 的write_notebook等机制导出随后被移入docs/gallery/html/渲染 .rst 页面读取示例 Python 源码用 templates.py 中的DOC_TEMPLATEL46-L84生成文档源。该模板的结构值得注意可选的 deck.gl 文档外链.. raw:: html中的a iddeck-link.. raw:: html :file: ./html/{snake_name}.html——把上一步归档的 HTML 文件原样内嵌实现“文档页里直接运行示例”内联样式约束#deck-container { height: 50vh; width: 100% }以及让.wy-nav-content撑满宽度的max-width: 100% !important保证交互实例在 Sphinx 布局中有足够画幅“Source” 小节以.. code-block:: python输出完整示例源码写盘输出到docs/gallery/{资产名}.rst。入口main()L50-L56使用multiprocessing.Pool(processes4)并行处理EXAMPLE_GLOB中全部文件并在转换前mkdir -p建好 HTML 输出目录若一个示例文件都找不到会直接抛异常终止。页面标题由to_presentation_name()utils.py L4-L10生成名称含layer或view时做驼峰化处理并特判把json显示为Json其余情况做 title case。对应的构建入口是 docs/Makefile 的html-embeds目标它直接调用python scripts/embed_examples.py。3. 第二阶段generate_grid_html.py——画廊落地页generate_grid_html.py 逻辑非常薄调用HTML_TEMPLATE.render(grouped_examplesgrouped_examples(), ...)并把结果写入docs/gallery/grid.htmlL10-L13。复杂度都在模板侧HTML_TEMPLATEtemplates.py L3-L43要点外层用 CSS Grid 布局grid-template-columns: repeat(3, 1fr)、grid-gap: 20px即三列卡片按分组循环每个分组输出h2 classgallery-section-title标题分节顺序与标签即来自第 1 节所述grouped_examples()每个单元格链接到./gallery/{名称}.html卡片内容是 200px 宽的缩略图./_images/{名称}.png加标题文本to_presentation_name(名称)还带了一个悬停特效filter: hue-rotate(3.142rad)。注意链接的相对关系grid.html位于gallery/内页面链接指向gallery/{name}.html、图片指向_images/Sphinx 构建后_images为静态资源目录与embed_examples.py归档的 HTML、snap_thumbnails.py产出的 PNG 在命名上完全对齐——“以文件基本名为键”的约定在这里收束。该阶段由 Makefile 的html-grid-page目标触发Makefile L29-L31它会先执行html-embeds再运行网格生成保证页面与网格同步更新。4. 第三阶段snap_thumbnails.py——Playwright 截图管线snap_thumbnails.py 为每个示例生成画廊缩略图其 docstring 直接给出用法L3-L10# 安装依赖当前代码基线 uv pip install playwright Pillow playwright install chromium # 在 docs/ 目录下 make html-thumbnails # 为全部示例截图 python scripts/snap_thumbnails.py ../examples/widgets.py # 单个示例关键实现细节依赖切换脚本在导入playwright与PIL失败时会打印安装提示并退出L21-L28。注意 README 中旧版步骤写的是pip install pyppeteer pip install Image而当前源码已迁移到 Playwright Pillow实操时应以 docstring 与源码为准大示例白名单LARGE_EXAMPLES (bitmap_layer, icon_layer, heatmap_layer, terrain_layer, maplibre_globe)L32。这类示例数据集加载慢截图时不做networkidle等待改为固定goto后wait_for_timeout(10000)其余示例用wait_untilnetworkidle, timeout30000再额外等 3 秒让 deck.gl 完成渲染L75-L91截图流程snap()先经run_example()执行示例脚本、校验退出码与.html产物并移入HTML_DIR再启动 Chromium800×600 视口加载file://页面、wait_for_selector(canvas)确认画布出现后落盘 PNG外层snap_with_retries()提供 3 次重试L60-L109尺寸压缩shrink_image()用 Pillow 的Image.thumbnail((400, 300), Image.LANCZOS)原地压缩为 400×300 缩略图L112-L121失败语义main()汇总失败列表只要有任何一个缩略图失败就以RuntimeError终止L123-L140保证画廊不出现“有格子无图”的半成品状态。批量执行的构建入口是 docs/Makefile 的html-thumbnails目标uv run python scripts/snap_thumbnails.py。5. 实操按 README 步骤把新图层加入画廊README 的 “Adding a new layer to the gallery” 一节给出了官方流程结合当前源码可执行如下以下均在bindings/pydeck/docs/目录下操作# 0) 安装截图依赖README 原文pip install pyppeteer pip install Image # 当前源码已迁移到 Playwright请按 snap_thumbnails.py docstring 安装 uv pip install playwright Pillow playwright install chromium # 1) 把新示例如 examples/arc_layer.py注册进 docs/images.rst # images.rst 由 update_images_rst.py 自动生成注册缩略图 隐藏 toctree python scripts/update_images_rst.py # 2) 生成内嵌页面与画廊网格 make html-grid-page # 3) 为新示例创建缩略图 python scripts/snap_thumbnails.py ../examples/arc_layer.py # 若需要为多个示例文件建缩略图 make html-thumbnails各步骤与源码的对应关系注册images.rstREADME 要求手工维护 docs/images.rst而该文件实际由 update_images_rst.py 从EXAMPLE_NAMES重新渲染新增示例后重新生成即可保证图片注册与 toctree 条目齐全make html-grid-page等价于先跑embed_examples.py新示例获得gallery/{名称}.rst与gallery/html/{名称}.html再跑generate_grid_html.py网格出现新单元格缩略图单个示例走python scripts/snap_thumbnails.py ../examples/{名称}.py批量走make html-thumbnails产物落入docs/gallery/images/{名称}.png与网格模板中./_images/{名称}.png的引用同名对齐。6. 小结管线约定与扩展点整条管线的可维护性建立在几条严格约定之上命名即契约示例文件基本名snake_case贯穿 HTML、.rst、PNG 与 toctree 四个产物to_snake_case_string/to_presentation_name只负责展示层转换分组即目录examples/子目录名下划线转空格后 title-case决定画廊分区GROUP_ORDER固定 “Layers”“Extensions” 的展示顺序失败即终止embed_examples.py对“无示例文件”抛异常snap_thumbnails.py对任何缩略图失败抛RuntimeError避免文档站以不完整状态发布。常见扩展点为大数据集示例加长等待时间修改LARGE_EXAMPLES元组、调整缩略图尺寸THUMBNAIL_SIZE (400, 300)、调整网格列数HTML_TEMPLATE中的repeat(3, 1fr)以及把embed_examples.py中粗糙的layer字符串判断扩展为按视图等对象类型挂 deck.gl 回链。所有相关脚本集中在 docs/scripts/ 目录配合 docs/Makefile 的三个html-*目标即可完成一次完整的文档画廊再生成。【免费下载链接】deck.glWebGL2 powered visualization framework项目地址: https://gitcode.com/GitHub_Trending/de/deck.gl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考