From 6a485568a52a7ac13527fb19b909253890d2d7f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcel=20St=C3=B6r?= Date: Sun, 13 Jan 2019 17:30:23 +0100 Subject: [PATCH] Re-organize documentation Drops support for localized content, #2213 Restructure some content to match more closely what we have in master, #2542 --- docs/{en => }/build.md | 2 +- docs/de/index.md | 6 -- docs/en/index.md | 51 --------- docs/en/start.md | 5 - docs/{en => }/extn-developer-faq.md | 0 docs/{en => }/flash.md | 0 docs/{en => }/hardware-faq.md | 0 docs/index.md | 61 ++++++++--- docs/js/extra.js | 141 +------------------------ docs/{en => }/lua-developer-faq.md | 0 docs/{en => }/modules/adc.md | 2 +- docs/{en => }/modules/adxl345.md | 2 +- docs/{en => }/modules/am2320.md | 2 +- docs/{en => }/modules/apa102.md | 2 +- docs/{en => }/modules/bit.md | 2 +- docs/{en => }/modules/bme280.md | 2 +- docs/{en => }/modules/bmp085.md | 2 +- docs/{en => }/modules/cjson.md | 2 +- docs/{en => }/modules/coap.md | 2 +- docs/{en => }/modules/crypto.md | 2 +- docs/{en => }/modules/dht.md | 2 +- docs/{en => }/modules/encoder.md | 2 +- docs/{en => }/modules/enduser-setup.md | 4 +- docs/{en => }/modules/file.md | 2 +- docs/{en => }/modules/gdbstub.md | 2 +- docs/{en => }/modules/gpio.md | 2 +- docs/{en => }/modules/hmc5883l.md | 2 +- docs/{en => }/modules/http.md | 2 +- docs/{en => }/modules/hx711.md | 2 +- docs/{en => }/modules/i2c.md | 2 +- docs/{en => }/modules/l3g4200d.md | 2 +- docs/{en => }/modules/mdns.md | 2 +- docs/{en => }/modules/mqtt.md | 2 +- docs/{en => }/modules/net.md | 2 +- docs/{en => }/modules/node.md | 2 +- docs/{en => }/modules/ow.md | 2 +- docs/{en => }/modules/pcm.md | 6 +- docs/{en => }/modules/perf.md | 2 +- docs/{en => }/modules/pwm.md | 2 +- docs/{en => }/modules/rc.md | 2 +- docs/{en => }/modules/rfswitch.md | 2 +- docs/{en => }/modules/rotary.md | 2 +- docs/{en => }/modules/rtcfifo.md | 4 +- docs/{en => }/modules/rtcmem.md | 4 +- docs/{en => }/modules/rtctime.md | 2 +- docs/{en => }/modules/sigma-delta.md | 2 +- docs/{en => }/modules/sntp.md | 2 +- docs/{en => }/modules/somfy.md | 4 +- docs/{en => }/modules/spi.md | 2 +- docs/{en => }/modules/struct.md | 2 +- docs/{en => }/modules/switec.md | 2 +- docs/{en => }/modules/tm1829.md | 2 +- docs/{en => }/modules/tmr.md | 2 +- docs/{en => }/modules/tsl2561.md | 2 +- docs/{en => }/modules/u8g.md | 2 +- docs/{en => }/modules/uart.md | 2 +- docs/{en => }/modules/ucg.md | 2 +- docs/{en => }/modules/websocket.md | 2 +- docs/{en => }/modules/wifi.md | 2 +- docs/{en => }/modules/ws2801.md | 2 +- docs/{en => }/modules/ws2812.md | 2 +- docs/{en => }/sdcard.md | 4 +- docs/{en => }/spiffs.md | 0 docs/{en => }/support.md | 2 +- docs/{en => }/upload.md | 2 +- mkdocs.yml | 133 ++++++++++++----------- 66 files changed, 176 insertions(+), 345 deletions(-) rename docs/{en => }/build.md (99%) delete mode 100644 docs/de/index.md delete mode 100644 docs/en/index.md delete mode 100644 docs/en/start.md rename docs/{en => }/extn-developer-faq.md (100%) rename docs/{en => }/flash.md (100%) rename docs/{en => }/hardware-faq.md (100%) rename docs/{en => }/lua-developer-faq.md (100%) rename docs/{en => }/modules/adc.md (96%) rename docs/{en => }/modules/adxl345.md (95%) rename docs/{en => }/modules/am2320.md (94%) rename docs/{en => }/modules/apa102.md (95%) rename docs/{en => }/modules/bit.md (97%) rename docs/{en => }/modules/bme280.md (98%) rename docs/{en => }/modules/bmp085.md (98%) rename docs/{en => }/modules/cjson.md (94%) rename docs/{en => }/modules/coap.md (99%) rename docs/{en => }/modules/crypto.md (99%) rename docs/{en => }/modules/dht.md (98%) rename docs/{en => }/modules/encoder.md (95%) rename docs/{en => }/modules/enduser-setup.md (97%) rename docs/{en => }/modules/file.md (99%) rename docs/{en => }/modules/gdbstub.md (97%) rename docs/{en => }/modules/gpio.md (98%) rename docs/{en => }/modules/hmc5883l.md (95%) rename docs/{en => }/modules/http.md (98%) rename docs/{en => }/modules/hx711.md (97%) rename docs/{en => }/modules/i2c.md (97%) rename docs/{en => }/modules/l3g4200d.md (95%) rename docs/{en => }/modules/mdns.md (96%) rename docs/{en => }/modules/mqtt.md (99%) rename docs/{en => }/modules/net.md (99%) rename docs/{en => }/modules/node.md (99%) rename docs/{en => }/modules/ow.md (98%) rename docs/{en => }/modules/pcm.md (92%) rename docs/{en => }/modules/perf.md (96%) rename docs/{en => }/modules/pwm.md (97%) rename docs/{en => }/modules/rc.md (86%) rename docs/{en => }/modules/rfswitch.md (99%) rename docs/{en => }/modules/rotary.md (98%) rename docs/{en => }/modules/rtcfifo.md (99%) rename docs/{en => }/modules/rtcmem.md (96%) rename docs/{en => }/modules/rtctime.md (99%) rename docs/{en => }/modules/sigma-delta.md (98%) rename docs/{en => }/modules/sntp.md (98%) rename docs/{en => }/modules/somfy.md (97%) rename docs/{en => }/modules/spi.md (99%) rename docs/{en => }/modules/struct.md (99%) rename docs/{en => }/modules/switec.md (98%) rename docs/{en => }/modules/tm1829.md (88%) rename docs/{en => }/modules/tmr.md (99%) rename docs/{en => }/modules/tsl2561.md (98%) rename docs/{en => }/modules/u8g.md (99%) rename docs/{en => }/modules/uart.md (98%) rename docs/{en => }/modules/ucg.md (99%) rename docs/{en => }/modules/websocket.md (99%) rename docs/{en => }/modules/wifi.md (99%) rename docs/{en => }/modules/ws2801.md (93%) rename docs/{en => }/modules/ws2812.md (99%) rename docs/{en => }/sdcard.md (96%) rename docs/{en => }/spiffs.md (100%) rename docs/{en => }/support.md (97%) rename docs/{en => }/upload.md (99%) diff --git a/docs/en/build.md b/docs/build.md similarity index 99% rename from docs/en/build.md rename to docs/build.md index eaf144d9..34ca70f5 100644 --- a/docs/en/build.md +++ b/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. \ No newline at end of file +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 deleted file mode 100644 index aa8cf10e..00000000 --- a/docs/de/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# NodeMCU Dokumentation - -NodeMCU ist eine [eLua](http://www.eluaproject.net/)-basierende firmware für den [ESP8266 WiFi SOC von Espressif](http://espressif.com/en/products/esp8266/). Dies ist ein Partnerprojekt für die beliebten [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0) - open source NodeMCU boards mit ESP8266-12E chips. - -Diese firmware nutzt das Espressif NON-OS SDK, das Dateisystem basiert auf [spiffs](https://github.com/pellepl/spiffs). - diff --git a/docs/en/index.md b/docs/en/index.md deleted file mode 100644 index 8000df91..00000000 --- a/docs/en/index.md +++ /dev/null @@ -1,51 +0,0 @@ -# NodeMCU Documentation - -NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/). The firmware is based on the Espressif NON-OS SDK and uses a file system based on [spiffs](https://github.com/pellepl/spiffs). The code repository consists of 98.1% C-code that glues the thin Lua veneer to the SDK. - -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. - -## 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` 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

Hello, NodeMCU.

") - 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) -``` - -```lua --- manipulate hardware like with Arduino -pin = 1 -gpio.mode(pin, gpio.OUTPUT) -gpio.write(pin, gpio.HIGH) -print(gpio.read(pin)) -``` - -## Getting Started -1. [Build the firmware](build.md) with the modules you need. -1. [Flash the firmware](flash.md) to the chip. -1. [Upload code](upload.md) to the firmware. - - diff --git a/docs/en/start.md b/docs/en/start.md deleted file mode 100644 index 9e2f59f0..00000000 --- a/docs/en/start.md +++ /dev/null @@ -1,5 +0,0 @@ -# Getting started -## Obtain the firmware -[Build the firmware](build.html) or download it from ? -## Flash the firmware -There are a number of tools for flashing the firmware. diff --git a/docs/en/extn-developer-faq.md b/docs/extn-developer-faq.md similarity index 100% rename from docs/en/extn-developer-faq.md rename to docs/extn-developer-faq.md diff --git a/docs/en/flash.md b/docs/flash.md similarity index 100% rename from docs/en/flash.md rename to docs/flash.md diff --git a/docs/en/hardware-faq.md b/docs/hardware-faq.md similarity index 100% rename from docs/en/hardware-faq.md rename to docs/hardware-faq.md diff --git a/docs/index.md b/docs/index.md index 48833aa6..311c3564 100644 --- 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. + +## 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

Hello, NodeMCU.

") + 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) +``` + +```lua +-- manipulate hardware like with Arduino +pin = 1 +gpio.mode(pin, gpio.OUTPUT) +gpio.write(pin, gpio.HIGH) +print(gpio.read(pin)) +``` + +## Releases + +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 `-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](en/index.md). It is part of the source code repository (`/docs` subfolder) and kept in sync with the code. - -We encourage you to help transferring the outdated translations (see below) into the repository. - -## 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). - -- 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) \ No newline at end of file +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 index fef3df6c..a01ee6bc 100644 --- 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'); - $('').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. - //