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"
}