How to Contribute to Documentation

文档有两种类型，即 markdown 文件和 API 使用参考。本指南介绍了一些工具，并指导如何准备 md 文件和 API 注释。

md 文件将通过Docusaurus构建成 HTML 页面；API 注释（来自源代码）将用于使用 Sphinx（对应 Python）和 Doxygen（对应 CPP）生成 API 参考页面。

Markdown 文件

请尽量遵循Google Documentation style。例如：

删除指令中的"please"。如：'Please click...' VS 'Click...'。
遵循标准的大小写规则。
在说明中用"you"代替"we"。
使用现在时态，避免使用will。
尽量使用主动语态而不是被动。

此外，为了使文件一致：

句子不宜过长, e.g., 长度<=80
尽量使用相对路径，假设我们在 repo 的根目录下，例如，doc-site/docs指的是singa-doc/docs-site/docs。
使用背标将命令、路径、类函数和变量亮出来，例如，Tensor, singa-doc/docs-site/docs。
为了突出其他术语/概念，使用斜体 or 加粗

本项目使用的prettier tool会在我们进行 git 提交时，根据配置自动格式化代码。例如，它会将 markdown 文件中的文本最多折叠成 80 个字符（注释行除外）。

在介绍一个概念（如Tensor类）时，要提供概述（目的和与其他概念的关系）、API 和例子，还可以用 Google colab 来演示其用法。

详细的编辑 md 文件和建立网站的方法请参考本页面。

API References

CPP API

请遵循Google CPP 注释风格.

要生成文档，请从 doc 文件夹中运行 "doxygen"（推荐使用 Doxygen >= 1.8）。

Python API

请遵循Google Python DocString 风格.

Visual Studio Code (vscode)

如果你使用 vscode 作为编辑器，我们推荐使用以下插件。

Docstring Snippet

autoDocstring生成函数、类等的 docstring，要注意选择使用google的 docString 格式。

Spell Check

Code Spell Checker可以用来检查代码的注释，或.md和.rst文件。

要只对 Python 代码的注释进行拼写检查，可以在File - Preferences - User Snippets - python.json中添加以下代码段：

"cspell check" : {
"prefix": "cspell",
"body": [
    "# Directives for doing spell check only for python and c/cpp comments",
    "# cSpell:includeRegExp #.* ",
    "# cSpell:includeRegExp (\"\"\"|''')[^\1]*\1",
    "# cSpell: CStyleComment",
],
"description": "# spell check only for python comments"
}

如果要只对 Cpp 代码的注释进行拼写检查，可以在File - Preferences - User Snippets - cpp.json中添加以下代码段：

"cspell check" : {
"prefix": "cspell",
"body": [
    "// Directive for doing spell check only for cpp comments",
    "// cSpell:includeRegExp CStyleComment",
],
"description": "# spell check only for cpp comments"
}