Update RTD MkDocs (#3457)

* Modernize docs

* Remove old style hacks

* Add comment

.gitignore

@@ -9,9 +9,17 @@ app/
 components/*/.output/
 tools/toolchains
 extmods.ini
+.ccache
+bin
 
 #ignore Eclipse project files
 .cproject
 .project
 .settings/
+
+# ignore VS Code files
 .vscode/**
+
+# ignore IDEA files
+.idea
+*.iml

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+mkdocs:
+  configuration: mkdocs.yml
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: "3.7"
+  install:
+    - requirements: docs/requirements.txt

docs/css/extra.css

@@ -1,42 +1,7 @@
-blockquote {
-  padding: 0 15px;
-  color: #777;
-  border-left: 4px solid #ddd;
-}
-
-.rst-content blockquote {
-  margin: 0;
-}
-
-/*shifts the nested subnav label to the left to align it with the regular nav item labels*/
-ul.subnav ul.subnav span {
-  padding-left: 1.3em;
-}
-
-body {
-  font-size: 100%;
-}
-p {
-  line-height: 20px;
-  margin-bottom: 16px;
-}
-h1, h2 {
-  border-bottom: 1px solid #eee;
-  line-height: 1.2;
-  margin-top: 1.2em;
-  margin-bottom: 16px;
-}
-h3, h4, h5, h6 {
-  margin: 1em 0 0.7em 0;
-}
-code {
+/*https://github.com/mkdocs/mkdocs/issues/2538*/
+.wy-menu-vertical header,
+.wy-menu-vertical p.caption {
+  color: #55a5d9;
   font-size: 85%;
-  margin-right: 3px;
-}
-table.docutils td code {
-  font-size: 100%;
+  margin: 12px 0 0;
 }
-.wy-plain-list-disc, .rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {
-  line-height: 20px;
-  margin-bottom: 16px;
-}

docs/js/extra.js

@@ -43,9 +43,11 @@ var nodemcu = nodemcu || {};
    * replaces the relative path with an absolute path based on the selected branch.
    */
   function replaceRelativeLinksWithStaticGitHubUrl() {
-    var relativePath = "../../..";
+    var relativePath = "../..";
     var gitHubPath = "https://github.com/nodemcu/nodemcu-firmware/tree/" + determineSelectedBranch();
-    var gitHubLinks = $("a[href^='" + relativePath + "']").each(function (index) {
+    // 'div.section' denotes the container into which doc pages are integrated i.e. "the content" w/o navigation, 
+    // header, breadcrumbs, footer, etc. It's important that only links in this very section are manipulated.
+    var gitHubLinks = $("div.section a[href^='" + relativePath + "']").each(function (index) {
       var url = $(this).attr('href');
       $(this).attr('href', url.replace(relativePath, gitHubPath));
     });

docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs==1.2.2

mkdocs.yml

@@ -4,69 +4,70 @@ repo_url: https://github.com/nodemcu/nodemcu-firmware/
 
 theme:
   name: "readthedocs"
+  hljs_languages:
+    - lua
 strict: false
 
 markdown_extensions:
-#http://pythonhosted.org/Markdown/extensions/admonition.html
-- admonition:
-- toc:
-    permalink: True
+  #http://pythonhosted.org/Markdown/extensions/admonition.html
+  - admonition:
+  - toc:
+      permalink: True
 
-#requird due to https://github.com/rtfd/readthedocs.org/issues/1313
 #see http://mkdocs.readthedocs.org/en/latest/user-guide/styling-your-docs/#customising-a-theme
 extra_css:
-- css/extra.css
+  - css/extra.css
 extra_javascript:
-- js/extra.js
+  - js/extra.js
 
 pages:
-- Overview: 'index.md'
-- Basics:
-    - Building the firmware: 'build.md'
-    - Flashing the firmware: 'flash.md'
-    - Uploading code: 'upload.md'
-    - JTAG debugging: 'debug.md'
-    - Support: 'support.md'
-- FAQs:
-    - Lua Developer FAQ: 'lua-developer-faq.md'
-    - Extension Developer FAQ: 'extn-developer-faq.md'
-- Whitepapers:
-    - Filesystem on SD card: 'sdcard.md'
-    - Writing external C modules: 'modules/extmods.md'
-- C Modules:
-    - 'adc':          'modules/adc.md'
-    - 'bit':          'modules/bit.md'
-    - 'bthci':        'modules/bthci.md'
-    - 'can':          'modules/can.md'
-    - 'crypto':       'modules/crypto.md'
-    - 'dac':          'modules/dac.md'
-    - 'dht':          'modules/dht.md'
-    - 'encoder':      'modules/encoder.md'
-    - 'eth':          'modules/eth.md'
-    - 'file':         'modules/file.md'
-    - 'gpio':         'modules/gpio.md'
-    - 'http':         'modules/http.md'
-    - 'i2c':          'modules/i2c.md'
-    - 'i2s':          'modules/i2s.md'
-    - 'ledc':         'modules/ledc.md'
-    - 'mqtt':         'modules/mqtt.md'
-    - 'net':          'modules/net.md'
-    - 'node':         'modules/node.md'
-    - 'ota':          'modules/otaupgrade.md'
-    - 'ow (1-Wire)':  'modules/ow.md'
-    - 'pulsecnt':     'modules/pulsecnt.md'
-    - 'qrcodegen':    'modules/qrcodegen.md'
-    - 'sdmmc':        'modules/sdmmc.md'
-    - 'sigma delta':  'modules/sigma-delta.md'
-    - 'sjson':        'modules/sjson.md'
-    - 'sodium':       'modules/sodium.md'
-    - 'spi':          'modules/spi.md'
-    - 'struct':       'modules/struct.md'
-    - 'time':         'modules/time.md'
-    - 'tmr':          'modules/tmr.md'
-    - 'touch':        'modules/touch.md'
-    - 'u8g2':         'modules/u8g2.md'
-    - 'uart':         'modules/uart.md'
-    - 'ucg':          'modules/ucg.md'
-    - 'wifi':         'modules/wifi.md'
-    - 'ws2812':       'modules/ws2812.md'
+  - Overview: 'index.md'
+  - Basics:
+      - Building the firmware: 'build.md'
+      - Flashing the firmware: 'flash.md'
+      - Uploading code: 'upload.md'
+      - JTAG debugging: 'debug.md'
+      - Support: 'support.md'
+  - FAQs:
+      - Lua Developer FAQ: 'lua-developer-faq.md'
+      - Extension Developer FAQ: 'extn-developer-faq.md'
+  - Whitepapers:
+      - Filesystem on SD card: 'sdcard.md'
+      - Writing external C modules: 'modules/extmods.md'
+  - C Modules:
+      - 'adc': 'modules/adc.md'
+      - 'bit': 'modules/bit.md'
+      - 'bthci': 'modules/bthci.md'
+      - 'can': 'modules/can.md'
+      - 'crypto': 'modules/crypto.md'
+      - 'dac': 'modules/dac.md'
+      - 'dht': 'modules/dht.md'
+      - 'encoder': 'modules/encoder.md'
+      - 'eth': 'modules/eth.md'
+      - 'file': 'modules/file.md'
+      - 'gpio': 'modules/gpio.md'
+      - 'http': 'modules/http.md'
+      - 'i2c': 'modules/i2c.md'
+      - 'i2s': 'modules/i2s.md'
+      - 'ledc': 'modules/ledc.md'
+      - 'mqtt': 'modules/mqtt.md'
+      - 'net': 'modules/net.md'
+      - 'node': 'modules/node.md'
+      - 'ota': 'modules/otaupgrade.md'
+      - 'ow (1-Wire)': 'modules/ow.md'
+      - 'pulsecnt': 'modules/pulsecnt.md'
+      - 'qrcodegen': 'modules/qrcodegen.md'
+      - 'sdmmc': 'modules/sdmmc.md'
+      - 'sigma delta': 'modules/sigma-delta.md'
+      - 'sjson': 'modules/sjson.md'
+      - 'sodium': 'modules/sodium.md'
+      - 'spi': 'modules/spi.md'
+      - 'struct': 'modules/struct.md'
+      - 'time': 'modules/time.md'
+      - 'tmr': 'modules/tmr.md'
+      - 'touch': 'modules/touch.md'
+      - 'u8g2': 'modules/u8g2.md'
+      - 'uart': 'modules/uart.md'
+      - 'ucg': 'modules/ucg.md'
+      - 'wifi': 'modules/wifi.md'
+      - 'ws2812': 'modules/ws2812.md'