Edit

How to Contribute to Documentation

There are two types of documentation, namely markdown files and API usage reference. This guideline introduces some tools and instruction in preparing the source markdown files and API comments.

The markdown files will be built into HTML pages via Docusaurus; The API comments (from the source code) will be used to generate API reference pages using Sphinx (for Python) and Doxygen (for CPP).

Markdown Files

Try to follow the Google Documentation style. For example,

1. Remove 'please' from an instruction. 'Please click...' VS 'Click ...'.
2. Follow the standard captitalization rules.
3. Use 'you' instead of 'we' in the instructions.
4. Use present tense and avoid 'will'
5. Prefer active voice than passive voice.

In addition, to make the documentation consistent,

1. Keep the line short, e.g., length<=80
2. Use the relative path assuming that we are in the root folder of the repo, e.g., doc-site/docs refers to singa-doc/docs-site/docs
3. Higlight the command, path, class function and variable using backticks, e.g., Tensor, singa-doc/docs-site/docs.
4. To hightlight other terms/concepts, use graph or graph

The prettier tool used by this project will auto-format the code according to the configuration when we do git commit. For example, it will wrap the text in the markdown file to at most 80 characters (except the lines for comments).

When introducing a concept (e.g., the Tensor class), provide the overview (the purpose and relation to other concepts), APIs and examples. Google colab can be used to demonstrate the usage.

Refer to this page for the details on how to edit the markdown files and build the website.

API References

CPP API

Follow the Google CPP Comments Style.

To generate docs, run "doxygen" from the doc folder (Doxygen >= 1.8 recommended)

Python API

Follow the Google Python DocString Style.

Visual Studio Code (vscode)

If you use vscode as the editor, the following plugins are useful.

Docstring Snippet

autoDocstring generates the docstring of functions, classes, etc. Choose the DocString Format to google.

Spell Check

Code Spell Checker can be configured to check the comments of the code, or .md and .rst files.

To do spell check only for comments of Python code, add the following snippet via 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"
}

To do spell check only for comments of Cpp code, add the following snippet via 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"
}