Commit 5750da12 authored by Marcel Stör's avatar Marcel Stör
Browse files

Re-organize documentation

Drop support for localized content, #2213

Restructure some content to match more closely what we have in master, #2542
parent eb8d8b58
# NodeMCU Documentation # NodeMCU Documentation
NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP32](http://espressif.com/en/products/hardware/esp32/overview) and [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. NodeMCU is an open source [Lua](https://www.lua.org/) based firmware for the [ESP32](http://espressif.com/en/products/hardware/esp32/overview) and [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 ESP-IDF](https://github.com/espressif/ESP-IDF).
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.
Support for the new [ESP32 WiFi/BlueTooth SOC from Espressif](http://www.espressif.com/en/products/hardware/esp32/overview) is under way. Support for the new [ESP32 WiFi/BlueTooth SOC from Espressif](http://www.espressif.com/en/products/hardware/esp32/overview) is under way.
## Up-To-Date Documentation ## 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. 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.
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)
var nodemcu = nodemcu || {}; var nodemcu = nodemcu || {};
(function () { (function () {
'use strict'; 'use strict';
//var languageCodeToNameMap = {en: 'English', de: 'Deutsch'};
var languageCodeToNameMap = {en: 'English'};
var languageNames = values(languageCodeToNameMap);
var defaultLanguageCode = 'en';
$(document).ready(function () { $(document).ready(function () {
addToc(); addToc();
hideNavigationForAllButSelectedLanguage();
addLanguageSelectorToRtdFlyOutMenu();
replaceRelativeLinksWithStaticGitHubUrl(); replaceRelativeLinksWithStaticGitHubUrl();
}); });
...@@ -43,75 +37,13 @@ var nodemcu = nodemcu || {}; ...@@ -43,75 +37,13 @@ var nodemcu = nodemcu || {};
} }
} }
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 * 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 * on GitHub (i.e. when the page is viewed on GitHub) and on RTD they are defined with a relative URL. This function
* replaces the relative path with an absolute path based on the selected branch. * replaces the relative path with an absolute path based on the selected branch.
*/ */
function replaceRelativeLinksWithStaticGitHubUrl() { function replaceRelativeLinksWithStaticGitHubUrl() {
var relativePath = "../../../.."; var relativePath = "../../..";
var gitHubPath = "https://github.com/nodemcu/nodemcu-firmware/tree/" + determineSelectedBranch(); var gitHubPath = "https://github.com/nodemcu/nodemcu-firmware/tree/" + determineSelectedBranch();
var gitHubLinks = $("a[href^='" + relativePath + "']").each(function (index) { var gitHubLinks = $("a[href^='" + relativePath + "']").each(function (index) {
var url = $(this).attr('href'); var url = $(this).attr('href');
...@@ -119,48 +51,6 @@ var nodemcu = nodemcu || {}; ...@@ -119,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 * 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 * part of the location path. The code needs to distinguish between running MkDocs standalone
...@@ -173,7 +63,11 @@ var nodemcu = nodemcu || {}; ...@@ -173,7 +63,11 @@ var nodemcu = nodemcu || {};
if (window.location.origin.indexOf('readthedocs') > -1) { if (window.location.origin.indexOf('readthedocs') > -1) {
// path is like /en/<branch>/<lang>/build/ -> extract 'lang' // path is like /en/<branch>/<lang>/build/ -> extract 'lang'
// split[0] is an '' because the path starts with the separator // split[0] is an '' because the path starts with the separator
branch = path.split('/')[2]; var thirdPathSegment = path.split('/')[2];
// 'latest' is an alias on RTD for the 'dev' branch - which is the default for 'branch' here
if (thirdPathSegment != 'latest') {
branch = thirdPathSegment;
}
} }
return branch; return branch;
} }
......
# ADC Module # ADC Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2017-04-22 | | | [adc.c](../../../components/modules/bthci.c)| | 2017-04-22 | | | [adc.c](../../components/modules/bthci.c)|
The ADC module provides access to the in-built ADC1. The ADC module provides access to the in-built ADC1.
......
# bit Module # bit Module
| Since | Origin / Contributor | Maintainer | Source | | 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. Bit manipulation support, on 32bit integers.
......
# BT HCI Module # BT HCI Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2016-09-29 | [DiUS](https://github.com/DiUS), [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [bthci.c](../../../components/modules/bthci.c)| | 2016-09-29 | [DiUS](https://github.com/DiUS), [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [bthci.c](../../components/modules/bthci.c)|
The BT HCI module provides a minimal HCI-level interface to BlueTooth The BT HCI module provides a minimal HCI-level interface to BlueTooth
adverisements. Via this module you can set up BT LE advertisements and also adverisements. Via this module you can set up BT LE advertisements and also
......
# CAN Module # CAN Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2017-04-27 | [@ThomasBarth](https://github.com/ThomasBarth/ESP32-CAN-Driver/), zelll | | [can.c](../../../components/modules/can.c)| | 2017-04-27 | [@ThomasBarth](https://github.com/ThomasBarth/ESP32-CAN-Driver/), zelll | | [can.c](../../components/modules/can.c)|
The CAN module provides access to the in-built CAN controller. The CAN module provides access to the in-built CAN controller.
......
# DAC Module # DAC Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2018-10-14 | [Arnim Läuger](https://github.com/devsaurus) | [Arnim Läuger](https://github.com/devsaurus) | [dac.c](../../../components/modules/dac.c)| | 2018-10-14 | [Arnim Läuger](https://github.com/devsaurus) | [Arnim Läuger](https://github.com/devsaurus) | [dac.c](../../components/modules/dac.c)|
The DAC module provides access to the two built-in Digital to Analog Converters. The DAC module provides access to the two built-in Digital to Analog Converters.
......
# DHT Module # DHT Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2017-03-30 | [Arnim Läuger](https://github.com/devsaurus) | [Arnim Läuger](https://github.com/devsaurus) | [dht](../../../components/modules/dht.c)| | 2017-03-30 | [Arnim Läuger](https://github.com/devsaurus) | [Arnim Läuger](https://github.com/devsaurus) | [dht](../../components/modules/dht.c)|
## Constants ## Constants
Constants for various functions. Constants for various functions.
......
# encoder Module # encoder Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2016-02-26 | [Terry Ellison](https://github.com/TerryE) | [Terry Ellison](https://github.com/TerryE) | [encoder.c](../../../app/modules/encoder.c)| | 2016-02-26 | [Terry Ellison](https://github.com/TerryE) | [Terry Ellison](https://github.com/TerryE) | [encoder.c](../../app/modules/encoder.c)|
The encoder modules provides various functions for encoding and decoding byte data. The encoder modules provides various functions for encoding and decoding byte data.
......
# file Module # file Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2014-12-22 | [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [file.c](../../../components/modules/file.c)| | 2014-12-22 | [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [file.c](../../components/modules/file.c)|
The file module provides access to the file system and its individual files. The file module provides access to the file system and its individual files.
......
# GPIO Module # GPIO Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2016-11-26 | [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [gpio.c](../../../components/modules/gpio.c)| | 2016-11-26 | [Johny Mattsson](https://github.com/jmattsson) | [Johny Mattsson](https://github.com/jmattsson) | [gpio.c](../../components/modules/gpio.c)|
This module provides access to the [GPIO](https://en.wikipedia.org/wiki/General-purpose_input/output) (General Purpose Input/Output) subsystem. This module provides access to the [GPIO](https://en.wikipedia.org/wiki/General-purpose_input/output) (General Purpose Input/Output) subsystem.
......
# HTTP Module # HTTP Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2018-10-27 | [Tom Sutcliffe](https://github.com/tomsci) | [Tom Sutcliffe](https://github.com/tomsci) | [http.c](../../../components/modules/http.c)| | 2018-10-27 | [Tom Sutcliffe](https://github.com/tomsci) | [Tom Sutcliffe](https://github.com/tomsci) | [http.c](../../components/modules/http.c)|
HTTP *client* module that provides an interface to do GET/POST/PUT/DELETE over HTTP and HTTPS, as well as customized requests. It can support large requests with an API similar to that of the `net` module. Multiple concurrent HTTP requests are supported. Both synchronous and asynchronous modes are supported. HTTP *client* module that provides an interface to do GET/POST/PUT/DELETE over HTTP and HTTPS, as well as customized requests. It can support large requests with an API similar to that of the `net` module. Multiple concurrent HTTP requests are supported. Both synchronous and asynchronous modes are supported.
......
# I²C Module # I²C Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2014-12-22 | [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [i2c.c](../../../app/modules/i2c.c)| | 2014-12-22 | [Zeroday](https://github.com/funshine) | [Zeroday](https://github.com/funshine) | [i2c.c](../../app/modules/i2c.c)|
This module supports different interfaces for communicating via I²C protocol. All interfaces can be assigned to arbitrary GPIOs for SCL and SDA and can be operated concurrently. This module supports different interfaces for communicating via I²C protocol. All interfaces can be assigned to arbitrary GPIOs for SCL and SDA and can be operated concurrently.
......
# I2S Module # I2S Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2017-04-29 | zelll | [Arnim Läuger](https://github.com/devsaurus) | [i2s.c](../../../components/modules/i2s.c)| | 2017-04-29 | zelll | [Arnim Läuger](https://github.com/devsaurus) | [i2s.c](../../components/modules/i2s.c)|
The I2S module provides access to the in-built two I2S controllers. The I2S module provides access to the in-built two I2S controllers.
......
# LEDC Module # LEDC Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2017-07-05 | [Lars Stenberg](https://github.com/larsstenberg) | [Lars Stenberg](https://github.com/larsstenberg) | [ledc.c](../../../components/modules/ledc.c)| | 2017-07-05 | [Lars Stenberg](https://github.com/larsstenberg) | [Lars Stenberg](https://github.com/larsstenberg) | [ledc.c](../../components/modules/ledc.c)|
This module provides access to the [LEDC](http://esp-idf.readthedocs.io/en/latest/api-reference/peripherals/ledc.html) PWM driver. This module provides access to the [LEDC](http://esp-idf.readthedocs.io/en/latest/api-reference/peripherals/ledc.html) PWM driver.
......
# MQTT Module # MQTT Module
| Since | Origin / Contributor | Maintainer | Source | | Since | Origin / Contributor | Maintainer | Source |
| :----- | :-------------------- | :---------- | :------ | | :----- | :-------------------- | :---------- | :------ |
| 2018-10-08 | [Tuan PM](https://github.com/tuanpmt/esp_mqtt), [Espressif](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/protocols/mqtt.html) | | [mqtt.c](../../../components/modules/mqtt.c)| | 2018-10-08 | [Tuan PM](https://github.com/tuanpmt/esp_mqtt), [Espressif](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/protocols/mqtt.html) | | [mqtt.c](../../components/modules/mqtt.c)|
The client supports version 3.1 and 3.1.1 of the [MQTT](https://en.wikipedia.org/wiki/MQTT) protocol. Make sure that the correct version is set with `make menuconfig` -> "Component config" -> "ESP-MQTT Configurations" -> "Enable MQTT protocol 3.1.1". The client supports version 3.1 and 3.1.1 of the [MQTT](https://en.wikipedia.org/wiki/MQTT) protocol. Make sure that the correct version is set with `make menuconfig` -> "Component config" -> "ESP-MQTT Configurations" -> "Enable MQTT protocol 3.1.1".
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment