emsesp / docs

Official documentation for EMS-ESP

EMS-ESP Documentation

This is the official documentation for EMS-ESP and hosted on https://emsesp.github.io/docs/

Built on MkDocs using Material for MkDocs theme and borrowed from Tasmota.

Editing Articles

Edit only articles in /docs folder.

All paths are relative.

Use strict markdown syntax. See Markdown Cheatsheet for a quick reference.

Markdown Enhancements

Admonitions

Reference of all possibilities

Definition Lists

Usage

Tabs

Start each tab section with === "Tab title" and indent the tab content by 4 spaces. More information...

Warnings/Tips

!!! tip
    A tip

!!! warning
    A warning

!!! info "some info"

!!! note
    just a note

Superscript text

Enclose text in ^ ^ to superscript it. Example H^2^0 renders H²O

Installing

Easiest way is to run pip as a module (https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment). On Linux to install pip and this projects dependencies use:

• python3 -m venv venv to create the virtual environment
• source ./venv/bin/activate to enter it
• pip install wheel and pip install -r requirements.txt to install the libraries

Testing locally

• source ./venv/bin/activate to go into the virtual environment
• pip install -r requirements.txt to refresh latest libs
• mkdocs serve to build the documentation
• http://127.0.0.1:8000/docs
• TIP: comment out the git-committers in mkdocs.yml to speed up the build

Deploying manually

The GitHub actions take care of the re-deployments, but if you want to force it you can use:

mkdocs gh-deploy --force --strict

docs's Issues

Formatting of `Special functions`

The Remote thermostats section show odd in the wiki, but i can't see why, in editor preview all is ok.
Preview:

Wiki:

Migrate docsify to MkDocs

Planning to migrate this docsify generated markup over wiki to MkDocs (https://www.mkdocs.org/) using the Material UI theme (https://squidfunk.github.io/mkdocs-material/). It looks nicer, search is faster and I'm able to sort on tables which is needed for emsesp/EMS-ESP32#828