文档有两种类型,即markdown文件和API使用参考。本指南介绍了一些工具,并指导如何准备md文件和API注释。
md文件将通过Docusaurus构建成HTML页面;API注释(来自源代码)将用于使用Sphinx(对应Python)和Doxygen(对应CPP)生成API参考页面。
请尽量遵循Google Documentation style。例如:
will
。此外,为了使文件一致:
doc-site/docs
指的是singa-doc/docs-site/docs
。Tensor
, singa-doc/docs-site/docs
。本项目使用的prettier tool会在我们进行git提交时,根据配置自动格式化代码。例如,它会将markdown文件中的文本最多折叠成80个字符(注释行除外)。
在介绍一个概念(如Tensor
类)时,要提供概述(目的和与其他概念的关系)、API和例子,还可以用Google colab来演示其用法。
详细的编辑md文件和建立网站的方法请参考本页面。
请遵循Google CPP注释风格.
要生成文档,请从doc文件夹中运行 “doxygen”(推荐使用Doxygen >= 1.8)。
如果你使用vscode作为编辑器,我们推荐使用以下插件。
autoDocstring生成函数、类等的docstring,要注意选择使用google
的docString格式。
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" }