<!--
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
-->

# How to Contribute to Documentation

## Website

This document gives step-by-step instructions for deploying [SINGA website](http://singa.apache.org).

SINGA website is built by [Sphinx](http://www.sphinx-doc.org) from a source tree stored in the [git repo](https://github.com/apache/singa/tree/master/doc).

To install Sphinx:

    pip install -U Sphinx==1.5.6

To install the markdown support for Sphinx:

    pip install recommonmark==0.5.0

To install the rtd theme:

    pip install sphinx_rtd_theme==0.4.3

You can build the website by executing the following command from the doc folder:

    ./build.sh html

Committers can update the [SINGA website](http://singa.apache.org/en/index.html) by copying the updated files to the [website repo](https://github.com/apache/singa-site) (suppose the site repo is ~/singa-sit)

    cd _build
    rsync --checksum -rvh html/ ~/singa-site/
    cd ~/singa-site
    git commit -m "update xxxx"
    git push

We fix the versions of the libs in order to generate the same (checksum) html file if the source file is not changed. Otherwise, everytime we build the documentation, the html file of the same source file could be different. As a result, many html files in the site repo need updating.

## Python API

## CPP API

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

## Using Visual Studio Code (vscode)

### Preview

The document files (rst and md files) can be previewed in vscode via the [reStructuredText Extension](https://docs.restructuredtext.net/).

1. Install the extension in vscode.
2. Install the dependent libs. All libs required to build the website should be installed (see the above instructions). In addition, there are two more libs to be installed.

        pip install sphinx-autobuild=0.7.1
        pip install doc8=0.8.0
3. Configure the conf path for `restructuredtext.confPath` to the [conf.py](./conf.py)

### Docstring Snippet

[autoDocstring](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) generates the docstring of functions, classes, etc. Choose the DocString Format to `google`.

### Spell Check

[Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.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"
    }