Skip to content

Latest commit

 

History

History
418 lines (349 loc) · 13.3 KB

documentation-style-guide.md

File metadata and controls

418 lines (349 loc) · 13.3 KB
Raw

文档风格指南

本文档给出了针对 Fuchsia.dev 写作风格的指南。这些方针基于Google 开发者风格指南中的通用指导。

注意：本指南重点介绍了为 Fuchsia 编写文档的一些最佳做法。其中的某些主题在以下文档的资源中可能会得到更为广泛的探讨：

文字和链接

遵循 80 字符限制

在 Fuchsia 项目中，代码的行最大长度为 100 字符，而文档的行最大长度为 80 字符。该规则一个值得注意的例外情况是网址（即链接），写在一行中，不换行。

代码常使用缩进（页面左侧的空格），而英文散文（文档）多形成文字段落。这种差异导致了不同的宽度规格。

标记外部链接

请使用 {:.external} 标记任何不属于 fuchsia.dev、 fuchsia.googlesource.com 或 fuchsia-review.googlesource.com 的链接：

这是一个[外部](http://example.com){:.external}链接。

注意外部链接标志：这是一个外部{:.external}链接。

使用参考风格的链接

一般来说，Fuchsia 建议在 Markdown 文件中使用参考风格（reference-style）的链接。 参考风格链接使用与链接相关联的参考标识符，接下来每当您在文档中使用该链接时，即可引用该标识符。这使得文档中的链接易于更新。

推荐：请在您需要链接的位置创建标识符。

本例中，链接标识符称为 fuchsia-home：

欢迎来到 [Fuchsia 首页][fuchsia-home]。

接着在文档底部对其定义：

[fuchsia-home]: https://fuchsia.dev/

不推荐：编写如下的行内链接：

欢迎来到 [Fuchsia 首页](www.fuchsia.dev)。

您可以在外部的 Markdown 指南中阅读更多与参考风格链接有关的信息。

对不同的 Fuchsia 内容使用正确链接

在 Fuchsia 文档中您可以为三类内容添加链接：

  • /docs/ - 链接至位于 Fuchsia 源树中 /docs/ 目录内的文档。这些链接必须关联到具有 .md 扩展名的文件。例如，/concepts/README.md。
  • 源代码 - 链接至位于 Fuchsia 源树中的源代码文件。这些链接可以关联到任何文件扩展名，但这些文件必须存在于源树中。例如，/src/sys/sysmgr/main.cc。
  • 参考文档 - 链接至自动生成的 Fuchsia 参考文档。
    • 大多数 Fuchsia 参考文档不存在于源树内，但在 fuchsia.dev 上发布了。这些链接必须使用完全限定的网址。例如，https://fuchsia.dev/reference/fidl/fuchsia.io。
    • 不过，一些 Fuchsia 参考文档存在于源树内。这些文档位于 /reference/，并在 https://fuchsia.dev/fuchsia-src/reference/ 中发布。这些链接必须关联到具有 .md 扩展名的文件。例如，/reference/syscalls/bti_create.md。

测试您的链接后再提交更改

一旦创建了有效的 markdown 文件，您应当运行 doc-checker 以确保您的文件使用了有效的链接。当您试图提交包含 .md 文件的更改时，Gerrit 会运行 doc-checker，并会在您的提交中含有损坏链接时进行阻止。

要在本地运行 doc-checker，请使用 fx format-code 工具：

fx format-code

标题

为页面和章节标题使用句首字母大写格式

推荐：使用句首字母大写格式（sentence case）：

# This title is an example of sentence case

不推荐：使用标题词首大写格式（title case）：

# This Title is an Example of Title Case

为锚点使用连接号，不要使用下划线

默认情况下，fuchsia.dev 创建锚点时会在在空格处使用下划线（_）。不过，当引用一个页面中的章节时，请使用连接号（-，dash），使用 {#section-title} 创建自定义锚点。同样地，请在文件名中使用连接号。

推荐：为锚点使用连接号

 ## 这是一个章节标题 {#this-is-a-section-header}

代码样例

为 shell 命令样例使用 posix-terminal 格式化

推荐：为 shell 命令在 ``` 后添加 posix-terminal 能让读者更容易复制代码块中的内容。

```posix-terminal
fx ota
```

该代码块在渲染时，命令前会出现 $：

fx ota

不推荐：请勿在命令里硬编码 $ 字符。

$ fx ota

使用 none 以禁用复制功能

推荐：对于不需要读者复制内容的代码或输出样例，请在 ``` 后添加 none {:.devsite-disable-click-to-copy}。

```none {:.devsite-disable-click-to-copy}
$ my_command
不必复制和粘贴该代码块。
```

该代码块在渲染时，右上角没有复制标志：

$ my_command
不必复制和粘贴该代码块。

不推荐：为只需查看的内容启用复制功能。如果您在 ``` 之后不指定任何内容，那么复制功能默认是启用的。

```
$ my_command
不必复制和粘贴该代码块。
```

该代码块渲染为如下形式：

$ my_command
不必复制和粘贴该代码块。

引用源代码时使用路径，不要使用网址

推荐：任何引用源代码的链接应当仅使用路径引用。否则您将收到静态错误检查（static error check）。

更新[状态标头][sh]
[sh]: /zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h