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).
Try to follow the Google Documentation style. For example,
In addition, to make the documentation consistent,
doc-site/docs
refers to singa-doc/docs-site/docs
Tensor
, singa-doc/docs-site/docs
.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.
Follow the Google CPP Comments Style.
To generate docs, run “doxygen” from the doc folder (Doxygen >= 1.8 recommended)
Follow the Google Python DocString Style.
If you use vscode as the editor, the following plugins are useful.
autoDocstring generates the docstring of functions, classes, etc. Choose the DocString Format to google
.
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" }