Re-organize documentation

Drops support for localized content, #2213 Restructure some content to match more closely what we have in master, #2542
nodemcu · Jan 13, 2019 · 6a48556 · 6a48556
1 parent f03a8e4
commit 6a48556
Show file tree

Hide file tree

Showing 66 changed files with 174 additions and 343 deletions.
diff --git a/docs/en/build.md → docs/build.md b/docs/en/build.md → docs/build.md
@@ -11,4 +11,4 @@ NodeMCU "application developers" just need a ready-made firmware. There's a [clo
 Occasional NodeMCU firmware hackers don't need full control over the complete tool chain. They might not want to setup a Linux VM with the build environment. Docker to the rescue. Give [Docker NodeMCU build](https://hub.docker.com/r/marcelstoer/nodemcu-build/) a try.
 
 ## Linux Build Environment
-NodeMCU firmware developers commit or contribute to the project on GitHub and might want to build their own full fledged build environment with the complete tool chain. There is a [post in the esp8266.com Wiki](http://www.esp8266.com/wiki/doku.php?id=toolchain#how_to_setup_a_vm_to_host_your_toolchain) that describes this.
+NodeMCU firmware developers commit or contribute to the project on GitHub and might want to build their own full fledged build environment with the complete tool chain. There is a [post in the esp8266.com Wiki](http://www.esp8266.com/wiki/doku.php?id=toolchain#how_to_setup_a_vm_to_host_your_toolchain) that describes this.
diff --git a/docs/de/index.md b/docs/de/index.md
diff --git a/docs/en/index.md b/docs/en/index.md
diff --git a/docs/en/start.md b/docs/en/start.md
diff --git a/docs/en/extn-developer-faq.md → docs/extn-developer-faq.md b/docs/en/extn-developer-faq.md → docs/extn-developer-faq.md
diff --git a/docs/en/flash.md → docs/flash.md b/docs/en/flash.md → docs/flash.md
diff --git a/docs/en/hardware-faq.md → docs/hardware-faq.md b/docs/en/hardware-faq.md → docs/hardware-faq.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,18 +1,53 @@
 # NodeMCU Documentation
 
-!!! attention
-	This branch is frozen at the last commit before the Espressif SDK was upgraded to 2.0!
+NodeMCU is an open source [Lua](https://www.lua.org/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/) and uses an on-module flash-based [SPIFFS](https://github.com/pellepl/spiffs) file system. NodeMCU is implemented in C and is layered on the [Espressif NON-OS SDK](https://github.com/espressif/ESP8266_NONOS_SDK).
 
-NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/).  The NodeMCU *firmware* is a companion project to the popular [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0), ready-made open source development boards with ESP8266-12E chips.
+The firmware was initially developed as is a companion project to the popular ESP8266-based [NodeMCU development modules](https://github.com/nodemcu/nodemcu-devkit-v1.0), but the project is now community-supported, and the firmware can now be run on _any_ ESP module.
 
-## Up-To-Date Documentation
-At the moment the only up-to-date documentation maintained by the current NodeMCU team is in [English](en/index.md). It is part of the source code repository (`/docs` subfolder) and kept in sync with the code.
+## Programming Model
+The NodeMCU programming model is similar to that of [Node.js](https://en.wikipedia.org/wiki/Node.js), only in Lua. It is asynchronous and event-driven. Many functions, therefore, have parameters for callback functions. To give you an idea what a NodeMCU program looks like study the short snippets below. For more extensive examples have a look at the [`/lua_examples`](https://github.com/nodemcu/nodemcu-firmware/tree/master/lua_examples) folder in the repository on GitHub.
+
+```lua
+-- a simple HTTP server
+srv = net.createServer(net.TCP)
+srv:listen(80, function(conn)
+	conn:on("receive", function(sck, payload)
+		print(payload)
+		sck:send("HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n<h1> Hello, NodeMCU.</h1>")
+	end)
+	conn:on("sent", function(sck) sck:close() end)
+end)
+```
+```lua
+-- connect to WiFi access point
+wifi.setmode(wifi.STATION)
+wifi.sta.config("SSID", "password")
+```
+
+```lua
+-- register event callbacks for WiFi events
+wifi.sta.eventMonReg(wifi.STA_CONNECTING, function(previous_state)
+	if(previous_state==wifi.STA_GOTIP) then 
+	    print("Station lost connection with access point. Attempting to reconnect...")
+	else
+	    print("STATION_CONNECTING")
+	end
+end)
+```
 
-We encourage you to help transferring the outdated translations (see below) into the repository.
+```lua
+-- manipulate hardware like with Arduino
+pin = 1
+gpio.mode(pin, gpio.OUTPUT)
+gpio.write(pin, gpio.HIGH)
+print(gpio.read(pin))
+```
 
-## Outdated And Sparse Documentation
-The following translations are based on outdated documentation, use them with caution. The links point to the [NodeMCU wiki on GitHub](https://github.com/nodemcu/nodemcu-firmware/wiki).
+## Releases
 
-- Chinese, [中文](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_cn)
-- Russian, [русский](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_ru)
-- Spanish, [español](https://github.com/nodemcu/nodemcu-firmware/wiki/nodemcu_api_es)
+This project uses two main branches, `master` and `dev`. `dev` is actively worked on and it's also where PRs should be created against. `master` thus can be considered "stable" even though there are no automated regression tests. The goal is to merge back to `master` roughly every 2 months. Depending on the current "heat" (issues, PRs) we accept changes to `dev` for 5-6 weeks and then hold back for 2-3 weeks before the next snap is completed.
+
+A new tag is created every time `dev` is merged back to `master`. They are listed in the [releases section on GitHub](https://github.com/nodemcu/nodemcu-firmware/releases). Tag names follow the `<SDK-version>-master_yyyymmdd` pattern.
+
+## Up-To-Date Documentation
+At the moment the only up-to-date documentation maintained by the current NodeMCU team is in English. It is part of the source code repository (`/docs` subfolder) and kept in sync with the code.
diff --git a/docs/js/extra.js b/docs/js/extra.js
@@ -1,16 +1,9 @@
 var nodemcu = nodemcu || {};
 (function () {
   'use strict';
-  //var languageCodeToNameMap = {en: 'English', de: 'Deutsch'};
-  var languageCodeToNameMap = {en: 'English'};
-  var languageNames = values(languageCodeToNameMap);
-  var defaultLanguageCode = 'en';
 
   $(document).ready(function () {
     addToc();
-    fixSearch();
-    hideNavigationForAllButSelectedLanguage();
-    addLanguageSelectorToRtdFlyOutMenu();
     replaceRelativeLinksWithStaticGitHubUrl();
   });
 
@@ -44,96 +37,6 @@ var nodemcu = nodemcu || {};
     }
   }
 
-  /*
-   * RTD messes up MkDocs' search feature by tinkering with the search box defined in the theme, see
-   * https://github.com/rtfd/readthedocs.org/issues/1088. This function sets up a DOM4 MutationObserver
-   * to react to changes to the search form (triggered by RTD on doc ready). It then reverts everything
-   * the RTD JS code modified.
-   */
-  function fixSearch() {
-    var target = document.getElementById('rtd-search-form');
-    var config = {attributes: true, childList: true};
-
-    var observer = new MutationObserver(function(mutations) {
-      // if it isn't disconnected it'll loop infinitely because the observed element is modified
-      observer.disconnect();
-      var form = $('#rtd-search-form');
-      form.empty();
-      form.attr('action', 'https://' + window.location.hostname + '/en/' + determineSelectedBranch() + '/search.html');
-      $('<input>').attr({
-        type: "text",
-        name: "q",
-        placeholder: "Search docs"
-      }).appendTo(form);
-    });
-
-    if (window.location.origin.indexOf('readthedocs') > -1) {
-      observer.observe(target, config);
-    }
-  }
-
-  function hideNavigationForAllButSelectedLanguage() {
-    var selectedLanguageCode = determineSelectedLanguageCode();
-    var selectedLanguageName = languageCodeToNameMap[selectedLanguageCode];
-    // Finds all subnav elements and hides them if they're /language/ subnavs. Hence, all 'Modules' subnav elements
-    // won't be hidden.
-    // <ul class="subnav">
-    //   <li><span>Modules</span></li>
-    //   <li class="toctree-l1 ">
-    //     <a class="" href="EN/modules/node/">node</a>
-    //   </li>
-    $('.subnav li span').not(':contains(' + selectedLanguageName + ')').each(function (index) {
-      var spanElement = $(this);
-      if ($.inArray(spanElement.text(), languageNames) > -1) {
-        spanElement.parent().parent().hide();
-      }
-    });
-  }
-
-  /**
-   * Adds a language selector to the RTD fly-out menu found bottom left. Example:
-   *
-   * <dl>
-   *   <dt>Languages</dt>
-   *   <dd><a href="http://nodemcu.readthedocs.io/en/<branch>/de/">de</a></dd>
-   *   <strong>
-   *     <dd><a href="http://nodemcu.readthedocs.io/en/<branch>/en/">en</a></dd>
-   *   </strong>
-   * </dl>
-   *
-   * UGLY! That fly-out menu is added by RTD with an AJAX call after page load. Hence, we need to
-   * react to the subsequent DOM manipulation using a DOM4 MutationObserver. The provided structure
-   * is as follows:
-   *
-   * <div class="rst-other-versions">
-   *   <!-- Inserted RTD Footer -->
-   *   <div class="injected">
-   */
-  function addLanguageSelectorToRtdFlyOutMenu() {
-    var flyOutWrapper = $('.rst-other-versions');
-    // only relevant on RTD
-    if (flyOutWrapper.size() > 0) {
-      var observer = new MutationObserver(function (mutations) {
-        // since mutation on the target node was triggered we can safely assume the injected RTD div has now been added
-        var injectedDiv = $('.rst-other-versions .injected');
-        var selectedLanguageCode = determineSelectedLanguageCode();
-        var dl = document.createElement('dl');
-        var dt = document.createElement('dt');
-        dl.appendChild(dt);
-        dt.appendChild(document.createTextNode('Languages'));
-        for (var languageCode in languageCodeToNameMap) {
-          dl.appendChild(createLanguageLinkFor(languageCode, selectedLanguageCode === languageCode));
-        }
-        injectedDiv.prepend(dl);
-        // no need for that observer anymore
-        observer.disconnect();
-      });
-
-      // observed target node is the fly-out wrapper, the only event we care about is when children are modified
-      observer.observe(flyOutWrapper[0], {childList: true});
-    }
-  }
-
   /**
    * The module doc pages contain relative links to artifacts in the GitHub repository. For those links to work both
    * on GitHub (i.e. when the page is viewed on GitHub) and on RTD they are defined with a relative URL. This function
@@ -148,48 +51,6 @@ var nodemcu = nodemcu || {};
     });
   }
 
-  function createLanguageLinkFor(languageCode, isCurrentlySelected) {
-    var strong;
-    // split[0] is an '' because the path starts with the separator
-    var pathSegments = window.location.pathname.split('/');
-    var dd = document.createElement("dd");
-    var href = document.createElement("a");
-    href.setAttribute('href', '/' + pathSegments[1] + '/' + pathSegments[2] + '/' + languageCode);
-    href.appendChild(document.createTextNode(languageCode));
-    dd.appendChild(href);
-    if (isCurrentlySelected) {
-      strong = document.createElement("strong");
-      strong.appendChild(dd);
-      return strong;
-    } else {
-      return dd;
-    }
-  }
-
-  /**
-   * Analyzes the URL of the current page to find out what the selected language is. It's usually
-   * part of the location path. The code needs to distinguish between running MkDocs standalone
-   * and docs served from RTD. If no valid language could be determined the default language is
-   * returned.
-   *
-   * @returns 2-char language code
-   */
-  function determineSelectedLanguageCode() {
-    var selectedLanguageCode, path = window.location.pathname;
-    if (window.location.origin.indexOf('readthedocs') > -1) {
-      // path is like /en/<branch>/<lang>/build/ -> extract 'lang'
-      // split[0] is an '' because the path starts with the separator
-      selectedLanguageCode = path.split('/')[3];
-    } else {
-      // path is like /<lang>/build/ -> extract 'lang'
-      selectedLanguageCode = path.substr(1, 2);
-    }
-    if (!selectedLanguageCode || selectedLanguageCode.length > 2) {
-      selectedLanguageCode = defaultLanguageCode;
-    }
-    return selectedLanguageCode;
-  }
-
   /**
    * Analyzes the URL of the current page to find out what the selected GitHub branch is. It's usually
    * part of the location path. The code needs to distinguish between running MkDocs standalone
@@ -220,4 +81,4 @@ var nodemcu = nodemcu || {};
     }
     return values;
   }
-}());
+}());
diff --git a/docs/en/lua-developer-faq.md → docs/lua-developer-faq.md b/docs/en/lua-developer-faq.md → docs/lua-developer-faq.md
diff --git a/docs/en/modules/adc.md → docs/modules/adc.md b/docs/en/modules/adc.md → docs/modules/adc.md
@@ -1,7 +1,7 @@
 # ADC Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2014-12-24 | [Zeroday](https://github.com/funshine) | [jmattsson](https://github.com/jmattsson) | [adc.c](../../../app/modules/adc.c)|
+| 2014-12-24 | [Zeroday](https://github.com/funshine) | [jmattsson](https://github.com/jmattsson) | [adc.c](../../app/modules/adc.c)|
 
 The ADC module provides access to the in-built ADC.
 

diff --git a/docs/en/modules/adxl345.md → docs/modules/adxl345.md b/docs/en/modules/adxl345.md → docs/modules/adxl345.md
@@ -1,7 +1,7 @@
 # ADXL345 Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2016-04-08 | [Jason Schmidlapp](https://github.com/jschmidlapp) | [Jason Schmidlapp](https://github.com/jschmidlapp) | [adxl345.c](../../../app/modules/adxl345.c)|
+| 2016-04-08 | [Jason Schmidlapp](https://github.com/jschmidlapp) | [Jason Schmidlapp](https://github.com/jschmidlapp) | [adxl345.c](../../app/modules/adxl345.c)|
 
 
 This module provides access to the [ADXL345](https://www.sparkfun.com/products/9836) triple axis accelerometer.

diff --git a/docs/en/modules/am2320.md → docs/modules/am2320.md b/docs/en/modules/am2320.md → docs/modules/am2320.md
@@ -1,7 +1,7 @@
 # AM2320 Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2016-02-14 | [Henk Vergonet](https://github.com/hvegh) | [Henk Vergonet](https://github.com/hvegh) | [am2320.c](../../../app/modules/am2320.c)|
+| 2016-02-14 | [Henk Vergonet](https://github.com/hvegh) | [Henk Vergonet](https://github.com/hvegh) | [am2320.c](../../app/modules/am2320.c)|
 
 
 This module provides access to the [AM2320](https://akizukidenshi.com/download/ds/aosong/AM2320.pdf) humidity and temperature sensor, using the i2c interface.

diff --git a/docs/en/modules/apa102.md → docs/modules/apa102.md b/docs/en/modules/apa102.md → docs/modules/apa102.md
@@ -1,7 +1,7 @@
 # APA102 Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2016-01-26 | [Robert Foss](https://github.com/robertfoss)| [Robert Foss](https://github.com/robertfoss)| [apa102.c](../../../app/modules/apa102.c)|
+| 2016-01-26 | [Robert Foss](https://github.com/robertfoss)| [Robert Foss](https://github.com/robertfoss)| [apa102.c](../../app/modules/apa102.c)|
 
 This module provides Lua access to [APA102 RGB LEDs](https://youtu.be/UYvC-hukz-0) which are similar in function to the common [WS2812](ws2812) addressable LEDs.
 

diff --git a/docs/en/modules/bit.md → docs/modules/bit.md b/docs/en/modules/bit.md → docs/modules/bit.md
@@ -1,7 +1,7 @@
 # bit Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2014-12-24 | [https://github.com/LuaDist/bitlib](https://github.com/LuaDist/bitlib), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [bit.c](../../../app/modules/bit.c)|
+| 2014-12-24 | [https://github.com/LuaDist/bitlib](https://github.com/LuaDist/bitlib), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [bit.c](../../app/modules/bit.c)|
 
 
 Bit manipulation support, on 32bit integers.

diff --git a/docs/en/modules/bme280.md → docs/modules/bme280.md b/docs/en/modules/bme280.md → docs/modules/bme280.md
@@ -1,7 +1,7 @@
 # BME280 module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2016-02-21 | [vsky279](https://github.com/vsky279) | [vsky279](https://github.com/vsky279) | [bme280.c](../../../app/modules/bme280.c)|
+| 2016-02-21 | [vsky279](https://github.com/vsky279) | [vsky279](https://github.com/vsky279) | [bme280.c](../../app/modules/bme280.c)|
 
 This module provides a simple interface to [BME280/BMP280 temperature/air presssure/humidity sensors](http://www.bosch-sensortec.com/bst/products/all_products/bme280) (Bosch Sensortec).
 

diff --git a/docs/en/modules/bmp085.md → docs/modules/bmp085.md b/docs/en/modules/bmp085.md → docs/modules/bmp085.md
@@ -1,7 +1,7 @@
 # BMP085 Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2015-08-03 | [Konrad Beckmann](https://github.com/kbeckmann) | [Konrad Beckmann](https://github.com/kbeckmann) | [bmp085.c](../../../app/modules/bmp085.c)|
+| 2015-08-03 | [Konrad Beckmann](https://github.com/kbeckmann) | [Konrad Beckmann](https://github.com/kbeckmann) | [bmp085.c](../../app/modules/bmp085.c)|
 
 
 This module provides access to the [BMP085](https://www.sparkfun.com/tutorials/253) temperature and pressure sensor. The module also works with BMP180.

diff --git a/docs/en/modules/cjson.md → docs/modules/cjson.md b/docs/en/modules/cjson.md → docs/modules/cjson.md
@@ -1,7 +1,7 @@
 # CJSON Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2015-03-16 | [Mark Pulford](http://kyne.com.au/~mark/software/lua-cjson.php), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [cjson](../../../app/modules/cjson.c) |
+| 2015-03-16 | [Mark Pulford](http://kyne.com.au/~mark/software/lua-cjson.php), [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [cjson](../../app/modules/cjson.c) |
 
 The JSON support module. Allows encoding and decoding to/from JSON.
 

diff --git a/docs/en/modules/coap.md → docs/modules/coap.md b/docs/en/modules/coap.md → docs/modules/coap.md
@@ -1,7 +1,7 @@
 # CoAP Module
 | Since  | Origin / Contributor  | Maintainer  | Source  |
 | :----- | :-------------------- | :---------- | :------ |
-| 2015-02-04 | Toby Jaffey <[email protected]>, [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [coap.c](../../../app/modules/coap.c) |
+| 2015-02-04 | Toby Jaffey <[email protected]>, [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [coap.c](../../app/modules/coap.c) |
 
 The CoAP module provides a simple implementation according to [CoAP](http://tools.ietf.org/html/rfc7252) protocol.
 The basic endpoint server part is based on [microcoap](https://github.com/1248/microcoap), and many other code reference [libcoap](https://github.com/obgm/libcoap).