README.docs.md

Using ESP32-ThingsBoard-MQTT-Client SDK

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

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

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:

   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.

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

   (.venv) $ pip install recommonmark

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

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

   (.venv) $ pip install sphinx_rtd_theme

2. Add this theme extension module in conf.py

   html_theme = 'alabaster'

   to

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

   (.venv) $ pip install plantweb

Generate web pages

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

make html

Or

.\make html

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.