Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/avantec-iot/avantec-thingsboard

Using Avantec Thermostat with ThingsBoard
https://github.com/avantec-iot/avantec-thingsboard

Last synced: 1 day ago
JSON representation

Using Avantec Thermostat with ThingsBoard

Lists

README 

        
# Using Avantec HVAC devices with ThingsBoard



* [Read document](https://avantec-thingsboard.readthedocs.org)

* [Install tools](#install-tools)

* [Build document](#generate-web-pages)



This technical document is in the format of [reStructuredText](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html) and Markdown/[CommonMark](https://commonmark.org/). It's generated using [Sphinx](https://www.sphinx-doc.org/).



## 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.



1. 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 :



    * Windows:



    ```cmd

    > 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:



    ```sh

    $ 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.***



2. 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.



3. 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:



    ```sh

    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 ` is called.



### Step 2. Install recommonmark



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



1. Run the following command (using Command Prompt):



    ```sh

    (.venv) $ pip install recommonmark

    ```



2. Then in your `conf.py`:



    ```python

    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.



1. Run the following command (using Command Prompt):



    ```sh

    (.venv) $ pip install sphinx_rtd_theme

    ```



2. Add this theme extension module in ```conf.py```



    ```python

    html_theme = 'alabaster'

    ```



    to



    ```python

    # 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.



1. On Windows, run the following command (using Command Prompt):



    ```sh

    (.venv) $ pip install plantweb

    ```



## Generate web pages



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



```shell

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](./LICENSE).