📝 Implement new versioned Git docs (#341)

* ✨ Add versionned in-repo docs * 🐛 Attempt to fix encrypted key * 🐛 Fix permission issue on python exec * 🐛 Add mission import * 🐛 Fix relative path * 🐛 Add missing commit * ✨ Add index * 🎨 Change index design
homieiot · May 30, 2017 · c7db527 · c7db527
1 parent efff143
commit c7db527
Show file tree

Hide file tree

Showing 41 changed files with 1,669 additions and 7 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,6 +1,7 @@
+sudo: required
 language: python
-python:
-  - "2.7"
+services:
+  - docker
 
 env:
   - PLATFORMIO_CI_SRC=examples/CustomSettings
@@ -13,12 +14,36 @@ env:
   - PLATFORMIO_CI_SRC=examples/Broadcast
   - PLATFORMIO_CI_SRC=examples/GlobalInputHandler
   - CPPLINT=true
+  - DOCS=true
 
 install:
-  - pip install -U platformio
-  - pip install cpplint
-  # install current build as a library with all dependencies
-  - platformio lib -g install file://.
+  - chmod +x ./ci/generate_docs.py
 
 script:
-  - if [[ "$CPPLINT" ]]; then make cpplint; else platformio ci --board=esp01 --board=nodemcuv2; fi
+  - set -eo pipefail
+  - |
+    if [[ "${CPPLINT}" ]]; then
+      pip install cpplint
+      make cpplint
+    elif [[ "${DOCS}" ]]; then
+      openssl aes-256-cbc -d -in ./ci/id_rsa.enc -k "${PRIVATE_KEY_ENCRYPT_KEY}" >> /tmp/deploy_rsa
+      eval "$(ssh-agent -s)"
+      chmod 600 /tmp/deploy_rsa
+      ssh-add /tmp/deploy_rsa
+
+      ./ci/generate_docs.py -o /tmp/docs_site
+      pushd /tmp/docs_site
+      git init
+      git config --global user.name "travis-ci"
+      git config --global user.email "contact@travis-ci.com"
+      git remote add origin git@github.com:marvinroger/homie-esp8266.git
+      git add .
+      git commit -m ":package: Result of Travis build ${TRAVIS_BUILD_NUMBER}"
+      git push -f origin master:gh-pages
+      popd
+    else
+      pip install -U platformio
+      # install current build as a library with all dependencies
+      platformio lib -g install file://.
+      platformio ci --board=esp01 --board=nodemcuv2
+    fi
diff --git a/ci/docs_index_template.html b/ci/docs_index_template.html
@@ -0,0 +1,69 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>Homie for ESP8266 docs</title>
+
+    <meta charset="utf-8">
+
+    <style>
+      body {
+        background-color: #ef5350;
+      }
+
+      #content {
+        width: 512px;
+
+        margin: auto;
+
+        text-align: center;
+      }
+
+      h1, a {
+        font-family: "Segoe UI", Helvetica, Arial, sans-serif;
+      }
+
+      h1 {
+        color: white;
+      }
+
+      ul {
+        list-style-type: none;
+      }
+
+      li {
+        width: 100%;
+        height: 50px;
+
+        margin-bottom: 10px;
+
+        background-color: #ecf0f1;
+        border-bottom: 3px solid #bdc3c7;
+
+        line-height: 50px;
+      }
+
+      a {
+        display: block;
+        width: 100%;
+        height: 100%;
+
+        font-size: 30px;
+        text-decoration: none;
+        color: #2c3e50;
+      }
+
+      .description {
+        font-size: 15px;
+        color: #34495e;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="content">
+      <h1>Homie for ESP8266 docs</h1>
+
+      $versions_html
+    </div>
+  </body>
+</html>
diff --git a/ci/generate_docs.py b/ci/generate_docs.py
@@ -0,0 +1,74 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import json
+import urllib
+import urllib2
+import tempfile
+import zipfile
+import glob
+import subprocess
+import getopt
+import sys
+import shutil
+import os
+import string
+
+FIRST_RELEASE_ID=3084382
+VERSIONS = [
+  ('master', 'branch master (stable)', 'stable')
+]
+
+current_dir = os.path.dirname(__file__)
+output_dir = getopt.getopt(sys.argv[1:], 'o:')[0][0][1]
+github_releases = json.load(urllib2.urlopen('https://api.github.com/repos/marvinroger/homie-esp8266/releases'))
+
+def generate_docs(tag_name, description, destination_folder):
+  print('Generating docs for ' + tag_name + ' (' + description  + ') at /' + destination_folder + '...')
+  zip_url = 'https://github.com/marvinroger/homie-esp8266/archive/' + tag_name + '.zip'
+  zip_path = tempfile.mkstemp()[1]
+  urllib.urlretrieve(zip_url, zip_path)
+
+  zip_file = zipfile.ZipFile(zip_path, 'r')
+  unzip_path = tempfile.mkdtemp()
+  zip_file.extractall(unzip_path)
+  src_path = glob.glob(unzip_path + '/*')[0]
+
+  if not os.path.isfile(src_path + '/mkdocs.yml'): shutil.copy(current_dir + '/mkdocs.default.yml', src_path + '/mkdocs.yml')
+
+  subprocess.call(['docker', 'run', '--rm', '-it', '-p', '8000:8000', '-v', src_path + ':/docs', 'squidfunk/mkdocs-material', 'build'])
+  shutil.copytree(src_path + '/site', output_dir + '/' + destination_folder)
+  print('Done.')
+
+# Generate docs for branches
+
+for version in VERSIONS:
+  generate_docs(version[0], version[1], version[2])
+
+# Generate docs for releases
+
+for release in github_releases:
+  if (release['id'] < FIRST_RELEASE_ID): continue
+
+  tag_name = release['tag_name']
+  version = tag_name[1:]
+  description = 'release ' + version
+
+  VERSIONS.append((tag_name, description, version))
+  generate_docs(tag_name, description, version)
+
+# Generate index
+
+versions_html = '<ul>'
+for version in VERSIONS:
+  versions_html += '<li><a href="' + version[2] + '"># ' + version[0] + ' <span class="description">' + version[1] + '</span></a></li>'
+versions_html += '</ul>'
+
+docs_index_template_file = open(current_dir + '/docs_index_template.html')
+docs_index_template_html = docs_index_template_file.read()
+docs_index_template = string.Template(docs_index_template_html)
+docs_index = docs_index_template.substitute(versions_html=versions_html)
+
+docs_index_file = open(output_dir + '/index.html', 'w')
+docs_index_file.write(docs_index)
+docs_index_file.close()
diff --git a/ci/id_rsa.enc b/ci/id_rsa.enc
diff --git a/ci/id_rsa.pub b/ci/id_rsa.pub
@@ -0,0 +1 @@
+ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCkK7S8axcIlUN9CF3TUyL24VGxKeXnfZ0iSTcGI7qyyiAF5DEbgOLp0HavmA2gEg0SMnWfFiMOzl9+Kh8ejML2vhDD4VkDkMXepWN2f9v1TgkxFl/S6tyL1IIPy8TEOEdg74o6gYZJdIghP9Xd6Wuu1M4n7bh5kEWRshuSFD6r24YW1/ptiV9WkgTJyesjeS+6UwIWvHVFsjHZEC9lwXGu0knWLrYi0AMW0EUr6V5OHX1AdgipshmaOLDjdN25svG9XAQXxQVeM0jHMCYfP9p/yziJPdrIH5A6tQLHV3Qxc8QNNE8dKPq6zMj3KCrq5H3WGCsjkoQzT6/Hce8j5KWza4iDu0H8HgFgMGY0+/gDISYDNEDHHHO31LO0euW2E55WfkRqsVuhmWbjbnoYBSvy94u8NEKDSWZLRnuzjGJwh9YduirE8AycFdd1pbo6U/oMVB9Q1iTqb5yfSkiwodO6YG61K38d1Chwec/AEohA7kn2wL5rtIjYTuRevJgg4Ud8Lp8DIEUc82aK8/+bXUMPTZm44bJuH1267NMW/A8xyBoDrUtKtuwKI/eizfzC0sTVwYBBGddQBIqIpZePzkOMuunKg6+5r6QaLHMiCBtyNtwA7Hp8mpNXBh/KyavcJJDJQl/v9MQeP2Tw8qLolEjCnwH2vSJHfYzF6o6/JqPedw== marvin@DESKTOP-FASPR5U
diff --git a/ci/mkdocs.default.yml b/ci/mkdocs.default.yml
@@ -0,0 +1,29 @@
+site_name: Homie for ESP8266
+repo_name: 'marvinroger/homie-esp8266'
+repo_url: 'https://github.com/marvinroger/homie-esp8266'
+
+theme: material
+extra:
+  palette:
+    primary: red
+    accent: red
+
+markdown_extensions:
+  - meta
+  - footnotes
+  - codehilite
+  - admonition
+  - toc(permalink=true)
+  - pymdownx.arithmatex
+  - pymdownx.betterem(smart_enable=all)
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:pymdownx.emoji.to_svg
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tasklist(custom_checkbox=true)
+  - pymdownx.tilde
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,7 @@
+Welcome to the homie-esp8266 docs. This is also available at http://homie-esp8266.readthedocs.io/en/:version
+
+Replace `:version` by:
+
+* `latest` to access the latest development branch docs
+* `stable` to access the latest stable docs
+* `vx.x.x` to access specific version docs
diff --git a/docs/advanced-usage/branding.md b/docs/advanced-usage/branding.md
@@ -0,0 +1,8 @@
+By default, Homie for ESP8266 will spawn an `Homie-xxxxxxxxxxxx` AP and will connect to the MQTT broker with the `Homie-xxxxxxxxxxxx` client ID. You might want to change the `Homie` text:
+
+```c++
+void setup() {
+  Homie_setBrand("MyIoTSystem"); // before Homie.setup()
+  // ...
+}
+```
diff --git a/docs/advanced-usage/broadcast.md b/docs/advanced-usage/broadcast.md
@@ -0,0 +1,13 @@
+Your device can react to Homie broadcasts. To do that, you can use a broadcast handler:
+
+```c++
+bool broadcastHandler(const String& level, const String& value) {
+  Serial << "Received broadcast level " << level << ": " << value << endl;
+  return true;
+}
+
+void setup() {
+  Homie.setBroadcastHandler(broadcastHandler); // before Homie.setup()
+  // ...
+}
+```
diff --git a/docs/advanced-usage/built-in-led.md b/docs/advanced-usage/built-in-led.md
@@ -0,0 +1,19 @@
+By default, Homie for ESP8266 will blink the built-in LED to indicate its status. Note it does not indicate activity, only the status of the device (in `configuration` mode, connecting to Wi-Fi or connecting to MQTT), see [Getting started](../quickstart/getting-started.md) for more information.
+
+However, on some boards like the ESP-01, the built-in LED is actually the TX port, so it is fine if Serial is not enabled, but if you enable Serial, this is a problem. You can easily disable the built-in LED blinking.
+
+```c++
+void setup() {
+  Homie.disableLedFeedback(); // before Homie.setup()
+  // ...
+}
+```
+
+You may, instead of completely disable the LED control, set a new LED to control:
+
+```c++
+void setup() {
+  Homie.setLedPin(16, HIGH); // before Homie.setup() -- 2nd param is the state of the pin when the LED is o
+  // ...
+}
+```
diff --git a/docs/advanced-usage/custom-settings.md b/docs/advanced-usage/custom-settings.md
@@ -0,0 +1,38 @@
+Homie for ESP8266 lets you implement custom settings that can be set from the JSON configuration file and the Configuration API. Below is an example of how to use this feature:
+
+```c++
+HomieSetting<long> percentageSetting("percentage", "A simple percentage");  // id, description
+
+void setup() {
+  percentageSetting.setDefaultValue(50).setValidator([] (long candidate) {
+    return (candidate >= 0) && (candidate <= 100);
+  });
+
+  Homie.setup();
+}
+```
+
+An `HomieSetting` instance can be of the following types:
+
+Type | Value
+---- | -----
+`bool` | `true` or `false`
+`long` | An integer from `-2,147,483,648` to `2,147,483,647`
+`double` | A floating number that can fit into a `real64_t`
+`const char*` | Any string
+
+By default, a setting is mandatory (you have to set it in the configuration file). If you give it a default value with `setDefaultValue()`, the setting becomes optional. You can validate a setting by giving a validator function to `setValidator()`. To get the setting from your code, use `get()`. To get whether the value returned is the optional one or the one provided, use `wasProvided()`.
+
+For this example, if you want to provide the `percentage` setting, you will have to put in your configuration file:
+
+```json
+{
+  "settings": {
+    "percentage": 75
+  }
+}
+```
+
+See the following example for a concrete use case:
+
+[![GitHub logo](../assets/github.png) CustomSettings.ino](https://github.com/marvinroger/homie-esp8266/blob/develop/examples/CustomSettings/CustomSettings.ino)
diff --git a/docs/advanced-usage/deep-sleep.md b/docs/advanced-usage/deep-sleep.md
@@ -0,0 +1,29 @@
+Before deep sleeping, you will want to ensure that all messages are sent, including the `$online →  false`. To do that, you can call `Homie.prepareToSleep()`. This will disconnect everything cleanly, so that you can call `ESP.deepSleep()`.
+
+```c++
+#include <Homie.h>
+
+void onHomieEvent(const HomieEvent& event) {
+  switch(event.type) {
+    case HomieEventType::MQTT_CONNECTED:
+      Homie.getLogger() << "MQTT connected, preparing for deep sleep..." << endl;
+      Homie.prepareToSleep();
+      break;
+    case HomieEventType::READY_TO_SLEEP:
+      Homie.getLogger() << "Ready to sleep" << endl;
+      ESP.deepSleep();
+      break;
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+  Serial << endl << endl;
+  Homie.onEvent(onHomieEvent);
+  Homie.setup();
+}
+
+void loop() {
+  Homie.loop();
+}
+```