From f5dc3bd6bb9be36c0657a8f883492be0ec575c30 Mon Sep 17 00:00:00 2001 From: Bo Kou Date: Wed, 17 Jul 2024 23:15:40 +0800 Subject: [PATCH] feat: add how to contribute doc (#2239) --- docs/zh/_meta.json | 3 - docs/zh/how-to-contribute.mdx | 239 ++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+), 3 deletions(-) create mode 100644 docs/zh/how-to-contribute.mdx diff --git a/docs/zh/_meta.json b/docs/zh/_meta.json index aee7078f4..5ade02734 100644 --- a/docs/zh/_meta.json +++ b/docs/zh/_meta.json @@ -77,9 +77,6 @@ "collapse": true } }, - "how-to-write-docs": { - "title": "文档编写指南" - }, "en": { "display": "hidden" } diff --git a/docs/zh/how-to-contribute.mdx b/docs/zh/how-to-contribute.mdx new file mode 100644 index 000000000..fb4b98de8 --- /dev/null +++ b/docs/zh/how-to-contribute.mdx @@ -0,0 +1,239 @@ +--- +title: 如何参与文档贡献 +--- + +我们的文档底层基于 Nextra 实现，通过 `_meta.json` 来定义文件顺序、页面标题、页面布局等配置。 + +## 能力介绍 + +### TOC + +TOC(*Table-Of-Content*) 可以快速的让你的读者索引到特定的内容。你只需要设计好恰当的标题和层级结构，读者就可以通过页面右侧的 TOC 选单来实现文件内容的快速跳转。当然，你在书写文档时也可以时刻通过 TOC 来检查自己文档的层级结构设计的是否合理。 + +### MDX + +MDX 是一种基于 `.md` 的新的文档格式，它支持你在其中引入 React 组件来丰富文档的内容。新的官网也同时提供了一些内置 React 组件供你使用 + +```tsx filename="example.mdx" +some doc content that you write before... + + +You could write some additional information in that place. You also could use mardown syntax in it such as [link](#) or `code` + +``` + + +你当然可以继续使用 `.md` 来编写文档！不过可以尝试使用 `.mdx` 来为读者提供更好的阅读体验 + + + +### Callout + +Callout 组件与你在 markdown 中使用的引言语法 `> some text` 类似，不过它会以高亮块的方式来突出显示内容，从而更直观的传递一些信息。 +Callout 组件提供了四种类型: `info`，`warning`，`positive` 以及 `negative`，用来适配不同的是用场景。 + +例如，对于一般性的额外信息来说，我们可以使用 `info` 类型： + + + 这是一条需要额外说明的信息，可以使用 **加粗** 语法或者 `代码块` 语法。触控回调 **依赖物理引擎** ，使用此功能前请确保物理引擎已初始化完毕。 + + +对于一些可能对性能有影响的操作，可以使用 `warning` 类型增加醒目的提示： + + +需要注意的是，图片追踪在添加功能时就需要指定追踪的图片，并且在 WebXR 中，同张图片只会被追踪一次。 + + +对于一些推荐操作来说，或者最佳实践来说，可以使用 `positive` 类型： + + +点击`精灵图集`资产，通过调整 `打包设置` 的 `纹理最大宽度` 与 `纹理最大高度`，同时调用 `打包对象` 中的 `打包并预览` ，可以保证图集利用率在一个较高的水平。 + + +最后，对于 `breaking change`，或者某些非常不推荐的用法，可以使用 `negative` 类型： + + +注意，如果你没有把脚本资产绑定到实体的脚本组件上，则脚本不会运行 + + +### 图片缩放 + +新版官网引入了 `react-medium-image-zoom` 来实现了图片点击放大的功能。你可以使用下面的方式来实现： + +````mdx filename="your-doc.mdx" +import { Image } from '@/mdx' + + + +```` + + + + +由于我们之前文档中的图片是 markdown 语法和 img 标签混用的，新版在解析时无法正确区分这两种情况。导致无法直接将此功能应用到所有图片中。 +举例来说，我们在文档中有时候会在一行内显示某个按钮截图，这时候就不应该使用缩放组件了。所以需要等老文档的图片语法更新后才可以全量使用 + + +### 代码高亮 + +新版的代码高亮功能十分强大，你不仅可以在行内代码和独立代码块中实现代码高亮，对于独立代码块，还新增了 **行显示**，**文件名指定**，**行高亮**，**区间高亮**，**关键词高亮** 等特色功能。 + +#### 行内高亮 + +```md +`let x = 1{:ts}` +``` + +比如，这是一段嵌入到文字中的代码 `let x = 1{:ts}`, 可以看到 TypeScript 代码有了高亮的效果。 + +#### 文件名 + +下面的示例包括了如何显示文件名，以及如何显示行指示器。 + +````md filename="script-component.mdx" +```ts showLineNumbers filename="example.ts" +class CustomScript extends Script { + @ignoreClone + a:boolean = false; + @assignmentClone + b:number = 1; + @shallowClone + c:Vector3[] = [new Vector3(0,0,0)]; +} +``` +```` + +上面的语法产生的效果如下： + +```ts showLineNumbers filename="example.ts" +class CustomScript extends Script{ + @ignoreClone + a:boolean = false; + @assignmentClone + b:number = 1; + @shallowClone + c:Vector3[] = [new Vector3(0,0,0)]; +} +``` + + +使用文件名的场景可能并不常见，但某些情况下显示文件名是有必要的。譬如，对于 `project.json` 或 `Scene.json` 这种文件内容，增加文件名的显示可以更直观的传递信息。 + + +#### 行高亮 + +````md filename="Markdown" +```ts {1,4-5} +async function setupDefaultScene(scene: Scene){ + const root = scene.createRootEntity(); + const cameraEntity = root.createChild(); + cameraEntity.transform.setPosition(0, 0, 10); + cameraEntity.addComponent(Camera); + cameraEntity.addComponent(OrbitControl); +} +``` +```` + +通过 `{1,4-5}` 这样的语法，我们可以同时实现单行高亮和多行高亮的功能。 + +```js {1,4-5} showLineNumbers +async function setupDefaultScene(scene: Scene) { + const root = scene.createRootEntity(); + const cameraEntity = root.createChild(); + cameraEntity.transform.setPosition(0, 0, 10); + cameraEntity.addComponent(Camera); + cameraEntity.addComponent(OrbitControl); +} +``` + +#### 指定代码高亮 + +在某些情况下，你可能需要用户关注某一个关键方法，或某一个类的名称。这时候就可以使用 ` ```ts /specularTexture/ ` 语法来实现指定代码高亮的功能。 + +````md filename="Markdown" +```ts /specularTexture/ + engine.resourceManager + .load({ + type: AssetType.Env, + url: "https://gw.alipayobjects.com/os/bmw-prod/6470ea5e-094b-4a77-a05f-4945bf81e318.bin", + }) + .then((ambientLight) => { + scene.ambientLight = ambientLight; + skyMaterial.texture = ambientLight.specularTexture; + skyMaterial.textureDecodeRGBM = true; + openDebug(ambientLight.specularTexture); + engine.run(); + }); +``` +```` +上面的语法产生的效果如下： + +```ts /specularTexture/ +engine.resourceManager + .load({ + type: AssetType.Env, + url: "https://gw.alipayobjects.com/os/bmw-prod/6470ea5e-094b-4a77-a05f-4945bf81e318.bin", + }) + .then((ambientLight) => { + scene.ambientLight = ambientLight; + skyMaterial.texture = ambientLight.specularTexture; + skyMaterial.textureDecodeRGBM = true; + openDebug(ambientLight.specularTexture); + engine.run(); + }); + +``` + +### 嵌入示例 + +在之前，你使用的是 `{:html}` 语法来嵌入的示例。新版的官网对此语法也做了兼容。但后续嵌入示例时推荐使用下面新的语法。毕竟，这里嵌入的示例只是一个 iframe 而已。 + +````mdx filename="light.mdx" +... + +Ambient light emits from all directions and enters the eye, as shown in the example below: + + + +... +```` + +## 新增文档 + +新增文档相较于之前可能多了一些步骤（在某些情况下）。需要提前说明的是，在新的官网中，文件路径即是路由。同时文档的顺序以及标题需要使用 `_meta.json` 进行配置。 + +以新增动画系统的文档 joint 来说： + +1. 新增文档 `docs/animation/joint.mdx` +2. 为文档新增 frontMatter。目前支持的字段有: + 1. **title** 文档标题 + 2. **group** 文档子标题 + 3. **banner** 头图 +3. 编写文档内容 +4. 修改 `animation/_meta.json` 来定义文档的顺序和侧边栏中的标题 + +对于文档国际化而言，则同步在 `/docs/en` 文件夹中做上述操作 + +## 新增博客 + +新增博客与新增文档的过程类似，只是 frontMatter 多了一些支持的字段。 + +1. 新增博客文档 `blog/new_blog.mdx` +2. 为博客增加 frontMatter, 支持的字段有： + 1. **title** 博客标题 + 2. **group** 博客分类，可使用英文 `,` 隔开多个 group 名称 + 3. **banner** 头图 + 4. **published** 发布时间。年月日格式，例如 `2024-03-14` + 5. **author** 博客作者定义。包含 name avatar website 三个字段 + 6. **searchable** 需要配置为 `searchable: false` 从而避免被内置的搜索引擎搜索到 + 7. **summary** 博客的摘要，会显示在博客列表页中 + +## 新增 Changelog + +和新增博客的过程一样，只不过文件位于 `/changelog` 中。 + +## 新增示例 + +除了以往的单文件示例开发外，我们许你将一个大的示例进行拆分。比如将资产文件列表拆分成一个 `json`，或者将 `dat-gui` 的配置拆分到 `gui-config.ts` 中等等。 + +要实现文件拆分，你只需要在 `examples` 文件中新建示例文件夹，确保文件夹中包含一个 `index.ts` 即可。在示例页面生成时，会自动检测代码中所依赖的其他文件，并注入到工作区中。 \ No newline at end of file