企业官网建设流程全解析

PennyLane Demos 使用入门：demo CLI 工具从创建到构建 HTML 完整教程

【免费下载链接】demosIntroductions to key concepts in quantum programming, as well as tutorials and implementations from cutting-edge quantum computing research.项目地址: https://gitcode.com/gh_mirrors/qml/demos

PennyLane Demos 是一个开源量子计算演示合集，收录了量子编程核心概念与前沿研究的教程。本教程将带你一步步使用内置的 demo CLI 工具，完成“创建演示 → 编写代码 → 构建 HTML”的完整流程，让你用几条命令就能把自己的量子程序发布成演示网页。

为什么需要 demo CLI 工具

手写演示项目涉及不少繁琐工作：建目录、填元数据 JSON、管理依赖版本、跑 Sphinx 构建……demo CLI 工具把整个过程封装成了 3 条命令：

CLI 的入口实现位于 lib/demo/app/app.py，命令解析基于typer框架。

第一步：一分钟一键安装 demo CLI

CLI 要求Python 3.11+（见 pyproject.toml），建议使用虚拟环境安装：

# 获取代码 git clone https://gitcode.com/gh_mirrors/qml/demos cd demos # 创建并激活虚拟环境 python3.11 -m venv .venv source .venv/bin/activate # 安装并验证 CLI 工具 pip install . demo

看到包含help/new/build的命令面板即安装成功。Windows 用户用\.venv\Scripts\activate激活环境即可。

📌 完整的安装说明与命令参考见 documentation/demo-cli.md。

第二步：用 demo new 创建你的第一个演示

执行demo new，按提示依次回答几个问题：

• Title：演示标题（不能为空）
• Custom directory name：目录名，会按标题自动生成下划线格式，可修改
• Description：一句话简介，用作网站 SEO 描述
• Author(s)：你的 pennylane.ai 用户名，可添加多位作者
• Thumbnail / Large Thumbnail：可选的缩略图路径，留空会使用占位图

确认后，CLI 会在demonstrations_v2/下生成标准三件套：

文件模板的生成逻辑在 lib/demo/lib/template.py，标题校验与目录名 slug 化规则在 lib/demo/app/app.py。

第三步：编写 demo 代码与 metadata 元数据

demo.py采用“文本 + 代码”混合写法：顶部 docstring 是可渲染的 Markdown 正文，代码按顺序执行，中间可加注释块把代码切分成独立单元格。可直接参考官方模板 documentation/reference_demo/demo.py。

metadata.json决定演示在站点的展示效果，字段说明见 demonstrations_metadata.md，改动前可对照最新校验规则 metadata_schemas/demo.metadata.schema.0.1.10.json。两个字段尤其重要：

• executable_stable/executable_latest：构建时是否真正执行代码。旧演示的目录名以tutorial_开头时，缺省也视为可执行
• previewImages：站点头像图，需放在_static/demo_thumbnails/下

全局公共依赖统一放在 dependencies/ 目录管理，你只需在requirements.in里补充自己额外的依赖。

第四步：用 demo build 构建 HTML 输出

代码写好后，一条命令即可构建：

# 构建指定演示为 HTML，并执行代码生成图表与输出 demo build --execute --format html your_demo_name # 不指定名称则构建全部演示 demo build

常用参数速查：

构建成功后：

• HTML 产物在_build/html/demos/<demo_name>/，直接用浏览器打开预览
• JSON 产物在_build/pack/<demo_name>/
• 注意：修改源文件后需重新构建，且本地构建不含完整样式与公式渲染

构建核心逻辑（创建虚拟环境、安装依赖、调用 sphinx-build）在 lib/demo/lib/demo.py，仓库根目录、构建目录等路径常量定义于 lib/demo/context.py。

常见构建问题速查

1. demo命令找不到：确认已激活虚拟环境且pip install .执行成功
2. 构建后没有代码输出：--execute只对executable_stable/executable_latest为 true 的演示生效
3. 缩略图不显示：图片必须放在regular_demo_thumbnails/或large_demo_thumbnails/目录，且metadata.json中的路径以/开头
4. 依赖版本冲突：用--venv指定独立环境，或在requirements.in中锁定版本

下一步去哪

• 到demonstrations_v2/浏览上百个现成演示，模仿其结构与写法
• 阅读 CONTRIBUTING.md 了解演示提交规范
• 分类命名规则见 demonstrations_categories.md

掌握 demo CLI 工具后，“写量子程序 → 发布成网页”从繁琐的多步流程缩短为几条命令。现在就敲下demo new，创建属于你的第一个量子演示吧！

【免费下载链接】demosIntroductions to key concepts in quantum programming, as well as tutorials and implementations from cutting-edge quantum computing research.项目地址: https://gitcode.com/gh_mirrors/qml/demos