编程语言编译器云原生语言运行时【免费下载链接】wingA programming language for the cloud ☁️ A unified programming model, combining infrastructure and runtime code into one language ⚡项目地址https://gitcode.com/gh_mirrors/wi/wing点击查看免费下载本篇指南面向 Wing 项目的贡献者与文档作者系统讲解如何为 Wing 开源仓库的官方文档docs 目录提交更新、在本地启动 Docusaurus 文档网站进行预览以及如何为 Examples 示例库 新增一个由 Markdown frontmatter 驱动的社区示例。读完本文你将掌握pnpm docs本地预览命令的底层原理、示例文件 frontmatter 全字段的含义与取值、如何在代码块中嵌入在线 Playground以及示例代码如何被自动抽取为测试用例的完整链路。一、文档仓库结构概览Wing 的全部官方文档都存放在仓库根目录下的docs目录中其内部又细分为若干子目录分别承载不同类型的内容docs/by-example/按主题组织的短小语言示例如 Hello world、HTTP Server、Json、Structs 等每个文件就是一个可独立阅读的示例页面docs/api/标准库 API 参考cloud、std、fs、http、math、util 等模块的 Markdown 与.yml定义文件docs/docs/概念性文档预飞行与飞行阶段 preflight/inflight、平台、模拟器、工具等docs/examples/社区模式与教程合集即本文重点讲解的 Examples 示例库docs/contributing/面向贡献者的文档本文即位于docs/contributing/01-start-here/08-docs.md。从仓库根目录的 package.json 可以看到docs脚本被直接挂载为根级 npm/pnpm 命令docs: ./scripts/docsite.sh也就是说文档网站的一切操作都可以从仓库根目录发起。二、如何更新文档直接提交 Pull Request官方文档的主体是纯 Markdown 文件。要提出文档更新不需要任何额外的构建流程直接对相应的 Markdown 文件发起 Pull Request 即可定位到目标文档对应的.md文件例如想修改示例库说明就编辑docs/examples/下的文件在分支上完成修改并提交向 Wing 仓库提交 Pull Request由维护者评审合并。文档页面顶部的 frontmatter如title、id、keywords、custom_edit_url等字段同时承担了 Docusaurus 侧边栏、SEO 关键词与在 GitHub 编辑此页链接的职责。以 docs/by-example/02-hello-world.md 为例其 frontmatter 就声明了slug: /hello-world、sidebar_label: Hello world与custom_edit_url这些字段共同决定了页面在文档站点中的路由与导航位置。三、在本地预览文档网站pnpm docs的原理与完整流程在提交 PR 之前贡献者通常希望先在本地看到文档的真实渲染效果。仓库提供了开箱即用的一行命令pnpm docs该命令的实际行为由 scripts/docsite.sh 实现其核心逻辑如下克隆/更新 docsite 框架将 Docusaurus 站点框架仓库winglang/docsite克隆到~/.winglang-docsite目录若目录已存在则执行git restore与git pull保持同步符号链接本地文档将仓库内的docs目录通过软链接ln -s挂载到 docsite 中的./docs位置保证文档站点展示的是你本地工作区的最新内容生成版本配置向 docsite 写入[current]版本的versions.json使站点以当前版本模式运行安装依赖并启动执行npm i安装 Docusaurus 依赖最后npm run start启动开发服务器并自动打开浏览器。从脚本实现scripts/docsite.sh可以看出几个实用细节克隆时使用了--depth1浅克隆以加快速度如果克隆失败脚本会自动清理~/.winglang-docsite并给出明确的错误提示每次运行时都会先重置 docsite 目录再重新建立软链接因此不会残留旧的本地内容。依赖项方面docs/目录自身是一个独立的winglang/docs包其 package.json 中定义了compile脚本tsx src/generate_examples_files.ts用于从文档示例代码块生成测试文件——这一点将在后文详细展开。四、Examples 示例库是什么docs/examples/是 Wing 的社区模式与教程集合旨在通过真实可运行的用例帮助开发者理解 Wing。当前仓库中已有以下示例文件basic-auth-api.md基于基本认证的 API 示例deploy-a-static-website.md静态网站部署示例introduction-to-wing.md与introduction-to-preflight-and-inflight.md交互式入门教程type为interactive tutorialprocessing-messages-in-a-queue.md队列消息处理模式quick-share.md综合演示应用 QuickShareredis.md结合 Redis winglib 的缓存写入模式。这些示例完全由Markdown 文件 frontmatter 元数据驱动——不需要编写任何站点代码新增一个示例本质上就是新增一个带有规范 frontmatter 的.md文件。五、新增一个示例的三步流程在docs/examples/目录下新增示例非常简单只需三步在 docs/examples 目录 下新建一个 Markdown 文件可以参考已有的processing-messages-in-a-queue.md在文件的 frontmatter 中填写示例的元信息在正文中用 Markdown 配以代码片段说明示例的用法与模式。5.1 frontmatter 字段详解以仓库中真实的 docs/examples/redis.md 为例其 frontmatter 完整呈现了示例文件支持的字段--- title: Using Redis with Wing subtitle: Example application that uses Redis to set values in a Redis cache type: - pattern platform: - awscdk - sim language: - wing githubURL: https://github.com/winglang/examples.git repoDirectory: examples/redis coverImage: /img/examples/redis.png coverImageInPage: true resources: - label: Redis winglib href: https://github.com/winglang/winglibs/tree/main/redis - label: Explore Wing functions href: /docs/api/standard-library/cloud/function authors: - name: David Boyne role: Developer Advocate, Wing twitter: https://twitter.com/boyney123 github: https://github.com/boyney123 cloudResources: - function ---各字段的含义与取值约定如下字段含义典型取值title示例页面上展示的标题任意字符串subtitle示例页面上展示的副标题/一句话摘要任意字符串type示例类型用于站点分类与筛选pattern模式或interactive tutorial交互式教程platform该示例支持编译运行的 Wing 平台awscdk、tf-aws、sim的组合language示例使用的语言wing或typescriptgithubURL示例完整源码所在的仓库地址如https://github.com/winglang/examples.gitrepoDirectory源码在仓库中的目录位置如examples/rediscoverImage示例卡片上渲染的封面图路径站点内图片路径如/img/examples/redis.pngcoverImageInPage是否在示例页面正文中展示封面图true/falseresources附加的学习资源链接列表每一项包含label与href指向 winglib、API 文档等authors作者信息可包含name、role、twitter、github对象数组cloudResources示例用到的云资源列表可选用于站点按资源过滤如function、queue、bucket、api不同字段的组合还能实现更精细的站点行为例如 docs/examples/deploy-a-static-website.md 额外使用了coverImageOptions按平台awscdk/tf-aws指定不同的封面图交互式教程类示例如 docs/examples/introduction-to-wing.md则通过url字段指向站外的在线课程地址。5.2 编写示例正文frontmatter 之后就是示例的正文内容。以 redis 示例为例正文先用文字描述模式再给出可直接运行的 Wing 代码bring redis; bring cloud; // Create a redis resource let redisInstance new redis.Redis(); new cloud.Function(inflight () { // Set value in the redis cache redisInstance.set(mykey, myvalue); });这段代码演示了一个典型的 preflight/inflight 组合redis.Redis()与cloud.Function在 preflight 阶段创建资源而函数内部的inflight闭包则在运行时通过 Redis 的 inflight API 写入缓存值。正文末尾通常还会附上本示例用到的资源清单方便读者跳转查阅对应 API例如 cloud function 标准库文档。封面图方面redis 示例引用了仓库内实际存在的配图 docs/examples/img/examples/redis.png它直观展示了 Function 模块调用 Redisset操作的架构关系5.3 在示例中嵌入在线 PlaygroundWing 提供了无需本地安装即可试玩的在线 Playground开发者可以直接在示例页面中嵌入它。做法非常简单在代码块的 fence 语言标识中追加playground关键字。例如 docs/examples/processing-messages-in-a-queue.md 中的代码块声明为js example playgroundbring cloud; bring util; bring expect; let bucket new cloud.Bucket(); let queue new cloud.Queue(); queue.setConsumer(inflight (message) { bucket.put(wing.txt, Hello, {message}); }, timeout: 30s); test Hello, world! { queue.push(world!); let found util.waitUntil(() { log(Checking if wing.txt exists); return bucket.exists(wing.txt); }); expect.equal(bucket.get(wing.txt), Hello, world!); }同样地docs/examples/basic-auth-api.md 中的js example playground代码块展示了完整的自定义BasicAuth类与 API 路由认证逻辑。playground关键字只影响页面渲染显示为可运行的 Playground 组件example关键字则与示例的自动化测试机制相关详见下一节。六、示例代码如何被自动抽取为测试Examples 示例并不只是展示用其中的代码会被自动抽取成可执行的测试用例。这一机制由 docs/src/generate_examples_files.ts 实现findExamples递归扫描文档目录下的所有.md文件extractExamples通过正则/.*? example.*?\n([\s\S]*?)/g提取所有带example关键字标记的代码块并解析代码块行内可选的 JSON 元数据如{ valid: false }generateTestsFromDocExamples将每个代码块写入tests/doc_examples/{valid|invalid}/目录下、以文件名_example_序号/main.w命名的测试工程中。在仓库中可以直接看到生成产物例如 tests/doc_examples/valid/processing-messages-in-a-queue.md_example_1/main.w其内容正是上一节队列示例代码块文件头部的注释标注了它的来源示例与元数据。也就是说只要示例代码块带example关键字它就会自动进入 Wing 的回归测试集这既保证了示例代码长期可运行也要求贡献者在写示例时必须保证代码真实可编译、可执行。该抽取逻辑由docs包的compile脚本见 docs/package.json触发与根目录的文档预览、CI 测试流程联动。七、小结贡献文档的完整工作流将以上内容串联起来一位文档贡献者的标准工作流是在 docs 下定位或新建目标.md文件若是 Examples 示例填写规范的 frontmatter参考 docs/examples/redis.md在正文中给出带playground/example关键字的代码块运行pnpm docs由 scripts/docsite.sh 拉起本地 Docusaurus 站点在浏览器中核验页面渲染、frontmatter 展示与 Playground 效果通过compile脚本docs/src/generate_examples_files.ts验证示例代码能被正确抽取为测试用例提交 Pull Request由维护者评审合并。通过这套流程文档既能在本地被真实预览示例代码又能持续经受自动化测试的检验从而保证 Wing 官方文档始终与仓库代码保持同步、可读且可信。赞分享编程语言编译器云原生语言运行时【免费下载链接】wingA programming language for the cloud ☁️ A unified programming model, combining infrastructure and runtime code into one language ⚡项目地址https://gitcode.com/gh_mirrors/wi/wing点击查看免费下载相关推荐Kubernetes Examples 仓库示例贡献指南从规范制定到高质量示例落地的完整实践Kubernetes Examples 仓库示例贡献指南从规范制定到高质量示例落地的完整实践 本文基于本仓库根目录下的 guidelines.md https示例工程symfony/process文档贡献指南完善API文档与示例symfony/process文档贡献指南完善API文档与示例 symfony/process是一个用于在PHP中执行命令行进程的库提供简单易用的API可后端Quartz.NET 仓库贡献指南从构建、测试到文档编写的完整工作流Quartz.NET 仓库贡献指南从构建、测试到文档编写的完整工作流 本指南围绕 Quartz.NET 开源仓库的 CONTRIBUTING.md https任务调度后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考