Using Avantec HVAC devices with ThingsBoard

Read document
Install tools
Build document

This technical document is in the format of reStructuredText and Markdown/CommonMark. It's generated using Sphinx.

Install tools

Prerequisites

Install Python 3.5+ (for Sphinx).

Step 1. Install Sphinx

Sphinx is a tool that makes it easy to create documentation.

Sphinx_intl is a useful tool for internationalization and localization.

On Windows, you should open Command Prompt (⊞Win-r and type cmd) and run the same command.

It is a good moment to create a Python virtual environment and install the required tools. For that, open a command line terminal, cd into the directory you just created, and run the following commands https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment:

Windows:

> cd /path/to/project
> python -m venv .venv                               # Creating a virtual environment
> .\.venv\Scripts\activate                           # Activating a virtual environment
(.venv) > where python                               # ...\.venv\Scripts\python.exe
(.venv) > python -m pip install sphinx sphinx_intl   # Installing packages
(.venv) > ...
(.venv) > deactivate                                 # Leaving the virtual environment

Linux:

$ cd /path/to/project
$ python -m venv .venv                               # Creating a virtual environment
$ source .venv/bin/activate                          # Activating a virtual environment
(.venv) $ which python                               # .../env/bin/python
(.venv) $ python -m pip install sphinx sphinx_intl   # Installing packages
(.venv) $ ...
(.venv) $ deactivate                                 # Leaving the virtual environment

Note: venv will create a virtual Python installation in the .venv folder. You should exclude your virtual environment directory from your version control system using .gitignore or similar.

After installation, type sphinx-build --version on the command prompt. If everything worked fine, you will see the version number for the Sphinx package you just installed.
Sphinx comes with a script called sphinx-quickstart that sets up a source directory and creates a default conf.py with the most useful configuration values from a few questions it asks you. To use this, run:
```
cd /path/to/project
(.venv) $ sphinx-quickstart docs
cd docs
```
We will be presented with a series of questions, the answer to which can depend from project to project.

Now we can see that some foldes and files have been autogenerated for us:
- conf.py : This is the file where all Sphinx configuration settings (including the settings we specified during the sphinx-quickstart setup) are specified.
- index.rst : This is the file which tells Sphinx how to render our index.html page.
- _static : image, script, etc.
- _build : This is the directory where the output of any builder is stored when a make <builder> is called.

Step 2. Install recommonmark

You can use Markdown and reStructuredText in the same Sphinx project.

Run the following command (using Command Prompt):
```
(.venv) $ pip install recommonmark
```
Then in your conf.py:
```
extensions = ['recommonmark']
extensions = ['sphinx.ext.autodoc']
```
Note: You should skip this step(2). The above code is already in you conf.py.

warning: Markdown doesn’t support a lot of the features of Sphinx, like inline markup and directives. However, it works for basic prose content. reStructuredText is the preferred format for technical documentation

Step 3. Install sphinx_rtd_theme

Sphinx_rtd_theme is a html theme.

Run the following command (using Command Prompt):
```
(.venv) $ pip install sphinx_rtd_theme
```

Add this theme extension module in conf.py

html_theme = 'alabaster'

# html_theme = 'alabaster'
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Note: You should skip this step(2). The above code is already in you conf.py.

Step 5. Install PlantUML

Plantuml is a library for generating UML diagrams from a simple text markup language.

On Windows, run the following command (using Command Prompt):
```
(.venv) $ pip install plantweb
```

Generate web pages

You can following this command to build HTML document at docs\:

make html  #.\make html #windows

Your index.rst has been built into index.html in your documentation output directory (typically _build/html/index.html). Open this file in your web browser to see your docs.

Licenses

This project is released under Apache 2.0 License.

avantec-iot/avantec-thingsboard