捐赠 爱心图标 GitHub 仓库

编写文档

与您使用过的其他大型、快速发展的开源库一样，Bevy 的文档总能得到改进。这是一个非常有价值且易于传播的工作，需要一些指导

  • 不准确的文档比没有文档更糟糕；优先修复损坏的文档。
  • Bevy 非常不稳定；在着手新的主要文档项目之前，请在 Discord 或 GitHub 上与社区联系（创建一个关于特定缺失文档的问题是一个很好的规划方式），了解该功能的稳定性和即将进行的计划，以避免不必要的麻烦。
  • 代码文档（文档示例和 examples 文件夹中的内容）更容易维护，因为编译器会在它出现问题时告诉我们。
  • 内联文档应该具有技术性和针对性。如果更广泛的上下文有用，请链接相关的示例或其他解释。
  • Bevy 手册托管在 bevy-website 仓库中，面向刚开始了解 Bevy（甚至 Rust！）的初学者。
  • 已接受的 RFC 并非文档；它们仅用作已接受决定的记录。

文档来源

我们有两个主要位置存放文档：代码库中的内联文档和 Bevy 的网站。

内联文档

每个版本的内联文档都会发布到 docs.rs。

要查看 main 分支上的当前文档，在您贡献之前，您可以访问 dev-docs.bevyengine.org，该网站包含从 main 分支的每次提交构建的最新 API 参考。

要检出您所做的任何本地更改

  1. 克隆 Bevy Engine GitHub 仓库并进入该目录
    1. git clone https://github.com/bevyengine/bevy.git
    2. cd bevy
  2. 运行 cargo doc --open

您的网络浏览器应打开，您应该能够从那里访问 docs.rs 页面的本地版本。

文档测试作为正常 cargo test 套件的一部分运行。要仅运行文档测试，可以使用 cargo test --doc。

网站

我们还认为 bevyengine.org 是我们核心文档的一部分。该网站有 自己的仓库，并且使用 Zola 静态网站引擎构建。根据我们的经验，它速度快、灵活且易于使用。

要检出您所做的任何本地更改

  1. 下载 Zola v0.19.2.
  2. 克隆 Bevy 的网站 GitHub 仓库并进入该目录
    1. git clone https://github.com/bevyengine/bevy-website.git
    2. cd bevy-website
  3. 使用 zola serve 启动 Zola 服务器。

本地服务器应启动，您应该能够从那里访问网站的本地版本。

学习材料结构

正如您可能已经注意到的，我们的入门学习材料分为两个主要部分

  1. 快速入门指南：“立即开始制作您的第一个游戏！”
  2. Bevy 手册：“了解 Bevy 的工作原理以及如何使用它”

这旨在迎合两种不同类型的学习者，而不会影响其中任何一方的体验

  • 示例优先：这些用户希望直接参与，查看所有内容的实际操作，并尽快获得一个可运行的游戏。这些用户通常心中有一个想法，他们希望尽快开始原型设计。
  • 定义优先：这些用户希望仔细建立一个 Bevy 的心理模型，在继续下一步之前彻底理解每个新概念。这些用户往往由好奇心驱动，或者旨在认真培养一项新技能。

重要的是，这些路径与学习者的经验水平无关！Bevy 旨在有意地接纳从未编程过的完全新手，以及来自其他引擎的专业人士。

初学者专业人士
示例优先热情的，希望创建一个他们喜欢的游戏的全新版本。探索性的，希望深入了解 Bevy 在实践中的表现。
定义优先好奇的，希望了解游戏制作的工作原理。批判性的，希望了解 Bevy 独特的架构选择。

它们中的每一个都需要自己的互补学习路径，这些路径在它们进入 学习页面 时就会分支，以确保它们对 Bevy 的第一次体验符合他们的需求。

一旦用户完成了他们在所选路径中的入门学习材料，他们就可以开始创建自己的游戏，或者继续学习我们的高级示例，看看所有内容如何以现实的方式组合在一起。

Bevy 快速入门：示例优先路径

遵循示例优先路径的用户往往会采取以下路线

  1. 由于社交媒体或口碑，遇到 Bevy 主页。
  2. 导航到学习页面。
  3. 选择一个最相关的快速入门游戏。
  4. 完成该教程。
  5. 深入制作他们心中的游戏，并在遇到障碍时根据需要访问以下资源
    1. 官方示例。
    2. Bevy 手册。
    3. 社区教程和模板游戏。
    4. 各种社区支持论坛。
    5. 流媒体、视频和博客。
    6. 高级示例。

每个快速入门游戏都应该

  1. 假设没有关于 Bevy 的现有知识。
  2. 首先进行对我们要构建的内容的高级解释。
  3. 首先介绍带注释的代码，然后解释每个关键术语的含义，以及它们出现的时间。
  4. 被分解成可编译的可玩部分；指南的每一页一个。
  5. 逐步重构代码以添加更多功能。
  6. 以一系列建议（以及适当的链接）结束，说明您可以如何以有趣的方式扩展游戏。

此路径应优先考虑

  1. 快速获得乐趣。
  2. 功能性、足够好的解释，这些解释与他们眼前的代码相关。
  3. 快速入门游戏与他们想要制作的游戏类型的相关性。
  4. 高资产质量。
  5. 轻松地使用他们自己的调整来扩展快速入门游戏。
  6. 解释如何通过文档、社区帮助和提交问题来摆脱困境。

Bevy 手册：定义优先路径

遵循定义优先路径的用户往往会采取以下路线

  1. 由于社交媒体或口碑，遇到 Bevy 主页。
  2. 导航到学习页面。
  3. 选择Bevy 手册。
  4. 按顺序阅读整本书。
  5. 一旦他们认为自己对引擎有了足够的了解，他们就会开始制作自己的游戏，通常是跳到示例优先路径上。
  6. 在探索时，他们还会浏览
    1. 源代码。
    2. docs.rs
    3. 贡献指南、GitHub 问题和 Pull Requests。
    4. 发行说明。
    5. Discord 上的引擎开发频道。
    6. 高级示例，看看所有内容如何组合在一起。

Bevy 手册的每一章都应该

  1. 有一个明确的主题，并对它将涵盖的子主题以及它们如何组合在一起进行高级概述。
  2. 被分解成几个部分/页面，以关注详细的主题。
    1. 这些应该有简单、最小的示例，解释该功能是如何工作的。
  3. 链接到快速入门指南的相应部分，这些部分以更连贯的方式演示了正在教授的想法。

此路径应优先考虑

  1. 清晰、彻底的解释。
  2. 以有条理的方式一次仔细介绍一个概念。
  3. 将概念在上下文中相互关联。
  4. 解释事物工作原理的技术细节，但仅在明确标记的旁注中。
  5. 传达所有支持 Bevy 生产力的开发实践
    1. 如何设置您的开发环境。
    2. 代码组织。
    3. 设计模式和最佳实践。
    4. 测试、基准测试和调试。
    5. 为 Bevy 本身做出贡献。
  6. 链接到进一步阅读，例如官方示例、docs.rs 和（非常谨慎地）源代码链接。

贡献者风格指南

在为 Bevy 手册、快速入门指南和其他相关学习材料编写和审查内容时，请尝试遵循以下指南

写作

  1. 使用清晰、简单的语言。
  2. 喜欢短句子。删除多余的单词。
  3. 在定义新词汇时，使用粗体。
    1. 在它们被引入后尽快定义它们。
  4. 确保您的语法和拼写正确。
  5. 避免成语和俚语。
  6. 以平易近人的语气直接与读者交谈。使用“我们”和“您”代词。
  7. 创建特定且命名的角色以说明一个观点可能很有用。
    1. 如果您这样做，请为他们选择一套代词并坚持下去。
    2. 否则，使用“他们/她们”第三人称代词来指代读者或其他人。
  8. 保持幽默。
    1. 避免不雅或冒犯性的幽默。
    2. 注意不要过度使用内部笑话或文化参考。
    3. 不要拖延你的笑话：这不是观众来这里阅读的内容。

组织

  1. 小心地将您的作品组织成单独的页面、标题、段落和代码块。
  2. 清楚地表明您何时正在技术深度解释一个概念，以便可以跳过它。
  3. 使用列表、编号列表和子列表以小块方式呈现信息。
    1. 按编号参考这些项目！
  4. 提供大量的链接，但请确保通过上下文可以明显地知道您要链接的内容。
    1. 当您提到它们时，链接到书籍/示例/网页的其他部分。
    2. 始终链接到您能找到的最具体的位置，无论是页面上的一个部分还是结构上的一个方法。
    3. 在链接到 Bevy 文档和源代码时使用 latest 标签，这样每次版本更新时它都不会过时。
    4. 在链接到详细的解释或讨论时，除了提供链接之外，还要总结最重要的要点。

技术

  1. 所有示例都必须能够编译和运行。

  2. 优先使用与游戏相关的描述性示例和变量名，而不是像 MyEvent 这样的通用名称。始终避免使用 foo 这样的无意义名称。

  3. 将代码分成块并添加注释或解释性文本是一种良好的做法，但您需要在最后链接到一个连贯且可复制的整体。

  4. 示例必须通过 Bevy 的标准 clippy lint 检查。

  5. 示例的精细程度应与您要传达的观点相符。

    1. 如果您要演示一个新功能，请尽可能只展示最基本的语法。
    2. 当尝试解释如何制作游戏时，请组织和完善您的代码以展示最佳实践。
    3. 缺乏精细程度应该有其目的：没有充分理由不要展示不良或草率的实践。
    4. 展示如何（以及为什么！）重构代码是一个非常强大的教学工具。

  6. 在每个示例中保持一致的风格（例如，for 循环与 map）。

  7. 如果您需要提供仅对部分受众有用的建议（例如，如何处理边缘情况或支持特定平台），请在明确标记的旁注（例如，调用框）或列表中进行。

  8. 示例不应使用或依赖于第三方插件。这些插件可能适合在示例末尾的“下一步”部分中链接。

    1. 第三方板条箱应限于最基本的一些，例如 rand。

  9. 要验证本地代码更改，您可以从任何位置运行 ./learning-code-examples/validate_examples.sh，或者从项目的根目录运行 cd learning-code-examples && cargo check --examples && cargo clippy --examples && cargo fmt --check。

  10. 要确保您的基于 Web 的文件（html、markdown）格式正确，请运行以下命令

    markdownlint -f -c .github/linters/.markdown-lint.yml .
djlint
typos

    在您本地 Bevy 网站存储库的根目录中。

    这将格式化 markdown 文件并告诉您 HTML 文件中的问题。为了运行该命令，您应该安装 markdownlint-cli、djlint 和 typos-cli。有关安装说明，请参阅：https://github.com/igorshubovych/markdownlint-cli、https://www.djlint.com/docs/getting-started/ 和 https://github.com/crate-ci/typos?tab=readme-ov-file#install。

  11. 要引用 Rust API 文档，您可以使用 markdown 的引用式链接，如下所示：HashMap

    [`HashMap`]

[`HashMap`]: https://doc.rust-lang.net.cn/std/collections/struct.HashMap.html
改善此页面