Tedee API documentation

Overview

This repository contains documentation for the Tedee API. It aims to help users integrate with the API by providing guides and code samples.

You can find a compiled version of this documentation here.

Visit our website: tedee.com.

Contribution

If you think there are areas that should be improved or extended, please let us know by creating an Issue. We also highly encourage you to contribute to this repo, whether you want to add a description, guide, or provide sample code.

Documentation specification

The documentation is:

• Written in RST markup
• Generated using Sphinx
• Hosted on ReadTheDocs

How to start

Prepare the infrastructure

To start working on this documentation, you need to install the required components. This is well described in the ReadTheDocs documentation. However, here's a quick list of what needs to be done:

• Install Python

  Note

  In the Python installation wizard, check the "Add Python to environment variables" option.

• Install Sphinx

  pip install sphinx

Prepare your environment

We find Visual Studio Code to be a great IDE for working on this documentation, and we configure some automation for it. Since it's written in RST markup, we recommend installing the RST Preview extension to highlight the syntax. It also allows you to immediately preview the document in the IDE using ctrl+shift+v or ctrl+k v to open preview to the side.

Regardless of the IDE used, please do the following:

1. Clone the repository

2. (Optional) Create and activate a virtual environment (venv):

   python3 -m venv venv
   source venv/bin/activate

3. Install all required dependencies from the docs/requirements.txt file.

   pip install -r requirements.txt

Build and test

Once you have installed all the required components, set up the environment, and cloned the repo, you're ready to make some changes. As mentioned earlier, you can preview your changes in the IDE. However, to get the full documentation running locally, you'll have to generate it.

To build the documentation:

1. If you use Visual Studio Code, run the build task (ctrl+shift+b)

2. OR if you use the terminal, go to the docs directory and execute the appropriate command for your operating system:

   • On Windows:

     .\make.bat html

   • On macOS/Linux:

     make html

3. After a while, you should get the _build folder created, where you can find the html directory with the index.html file inside. Open it.

Sometimes you may notice that after building, the files won't get updated. In such a case, we recommend running the make clean command or just removing the _build directory and trying again.

Pushing changes

Please make your changes in feature branches starting from the master branch, using the naming convention presented below:

• use only lowercase
• do not use whitespace
• do not use any special characters except: -/
• feature/[feature-description] - to implement new features, e.g. feature/authenticate-module
• fix/[bug-description] - to fix bugs, e.g. fix/incorrect-link

Once the changes are done and tested, you are ready to create a pull request.