Browse Source

Update RTD MkDocs (#3458)

Marcel Stör 2 years ago
parent
commit
2ccce2395d
7 changed files with 171 additions and 175 deletions
  1. 20 7
      .gitignore
  2. 15 0
      .readthedocs.yaml
  3. 7 44
      docs/css/extra.css
  4. BIN
      docs/img/favicon.ico
  5. 4 2
      docs/js/extra.js
  6. 1 0
      docs/requirements.txt
  7. 124 122
      mkdocs.yml

+ 20 - 7
.gitignore

@@ -1,24 +1,37 @@
+sdk/
+cache/
+user_config.h
+server-ca.crt
+sdkconfig
+sdkconfig.old*
+build/
+components/*/.output/
+tools/toolchains
+extmods.ini
+.ccache
+bin
+
 .gdb_history
 app/lua/.std
 app/lua53/.std
 sdk/
-cache/
-.ccache/
 local/
-user_config.h
-server-ca.crt
 luac.cross
 luac.cross.int
 uz_unzip
 uz_zip
-tools/toolchains/
 
 #ignore Eclipse project files
 .cproject
 .project
 .settings/
-.vscode
-.vs
+
+# ignore VS Code files
+.vscode/**
+
+# ignore IDEA files
+.idea
+*.iml
 
 #ignore temp file for build infos
 buildinfo.h

+ 15 - 0
.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

+ 7 - 44
docs/css/extra.css

@@ -1,48 +1,9 @@
-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%;
-}
-.wy-plain-list-disc, .rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {
-  line-height: 20px;
-  margin-bottom: 16px;
-}
-
-table#gs td {
-  text-align: center;
+  margin: 12px 0 0;
 }
 
 table#gs {
@@ -52,10 +13,12 @@ table#gs {
 }
 
 table#gs td {
+  text-align: center;
   font-size: 14px;
   padding: 10px 5px;
   color: #333;
   background-color: #fff;
+  white-space: unset;
 }
 
 table#gs th {

BIN
docs/img/favicon.ico


+ 4 - 2
docs/js/extra.js

@@ -45,9 +45,11 @@ var nodemcu = nodemcu || {};
    */
   function replaceRelativeLinksWithStaticGitHubUrl() {
     if (isOnRtd()) {
-      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));
       });

+ 1 - 0
docs/requirements.txt

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

+ 124 - 122
mkdocs.yml

@@ -4,6 +4,8 @@ repo_url: https://github.com/nodemcu/nodemcu-firmware/
 
 theme:
   name: "readthedocs"
+  hljs_languages:
+    - lua
 strict: false #Allows to build and test documentation in local environment where some links are unreachable
 
 # Uncomment the line below to build docs to be used locally; site/index.html
@@ -11,132 +13,132 @@ strict: false #Allows to build and test documentation in local environment where
 # use_directory_urls: 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
 
 #required 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:
-    - Getting started: 'getting-started.md'
-    - Building the firmware: 'build.md'
-    - Flashing the firmware: 'flash.md'
-    - Uploading code: 'upload.md'
-    - Compiling code: 'compiling.md'
-    - Support: 'support.md'
-- Reference:
-    - NodeMCU Language Reference Manual: 'nodemcu-lrm.md'
-    - Programming in NodeMCU: 'nodemcu-pil.md'
-- FAQs:
-    - Lua Developer FAQ: 'lua-developer-faq.md'
-    - Extension Developer FAQ: 'extn-developer-faq.md'
-    - Hardware FAQ: 'hardware-faq.md'
-- Whitepapers:
-    - Lua 5.3 Support: 'lua53.md'
-    - Lua Flash Store (LFS): 'lfs.md'
-    - Lua Compact Debug (LCD): 'lcd.md'
-    - Filesystem on SD card: 'sdcard.md'
-    - Internal filesystem: 'spiffs.md'
-- Lua Modules:
-    - 'Lua modules directory': 'lua-modules/README.md'
-    - 'bh1750': 'lua-modules/bh1750.md'
-    - 'bme280':  'lua-modules/bme280.md'
-    - 'cohelper': 'lua-modules/cohelper.md'
-    - 'ds18b20': 'lua-modules/ds18b20.md'
-    - 'ds3231': 'lua-modules/ds3231.md'
-    - 'fifo' : 'lua-modules/fifo.md'
-    - 'fifosock' : 'lua-modules/fifosock.md'
-    - 'file_lfs': 'lua-modules/file_lfs.md'
-    - 'ftpserver': 'lua-modules/ftpserver.md'
-    - 'gossip': 'lua-modules/gossip.md'
-    - 'hdc1000': 'lua-modules/hdc1000.md'
-    - 'httpserver': 'lua-modules/httpserver.md'
-    - 'imap': 'lua-modules/imap.md'
-    - 'liquidcrystal': 'lua-modules/liquidcrystal.md'
-    - 'lm92': 'lua-modules/lm92.md'
-    - 'mcp23008': 'lua-modules/mcp23008.md'
-    - 'mcp23017': 'lua-modules/mcp23017.md'
-    - 'redis': 'lua-modules/redis.md'
-    - 'telnet': 'lua-modules/telnet.md'
-    - 'yeelink': 'lua-modules/yeelink.md'
-- C Modules:
-    - 'adc': 'modules/adc.md'
-    - 'ads1115': 'modules/ads1115.md'
-    - 'adxl345' : 'modules/adxl345.md'
-    - 'am2320': 'modules/am2320.md'
-    - 'apa102': 'modules/apa102.md'
-    - 'bit': 'modules/bit.md'
-    - 'bloom' : 'modules/bloom.md'
-    - 'bme280': 'modules/bme280.md'
-    - 'bme280_math': 'modules/bme280_math.md'
-    - 'bme680': 'modules/bme680.md'
-    - 'bmp085': 'modules/bmp085.md'
-    - 'cjson': 'modules/cjson.md'
-    - 'coap': 'modules/coap.md'
-    - 'color-utils': 'modules/color-utils.md'
-    - 'cron': 'modules/cron.md'
-    - 'crypto': 'modules/crypto.md'
-    - 'dcc': 'modules/dcc.md'
-    - 'dht': 'modules/dht.md'
-    - 'encoder': 'modules/encoder.md'
-    - 'enduser setup / captive portal / WiFi manager': 'modules/enduser-setup.md'
-    - 'file': 'modules/file.md'
-    - 'gdbstub': 'modules/gdbstub.md'
-    - 'gpio': 'modules/gpio.md'
-    - 'hdc1080': 'modules/hdc1080.md'
-    - 'hmc5883l': 'modules/hmc5883l.md'
-    - 'http': 'modules/http.md'
-    - 'hx711' : 'modules/hx711.md'
-    - 'i2c' : 'modules/i2c.md'
-    - 'l3g4200d' : 'modules/l3g4200d.md'
-    - 'mcp4725': 'modules/mcp4725.md'
-    - 'mdns': 'modules/mdns.md'
-    - 'mqtt': 'modules/mqtt.md'
-    - 'net': 'modules/net.md'
-    - 'node': 'modules/node.md'
-    - 'ow (1-Wire)': 'modules/ow.md'
-    - 'pcm' : 'modules/pcm.md'
-    - 'perf': 'modules/perf.md'
-    - 'pipe': 'modules/pipe.md'
-    - 'pixbuf': 'modules/pixbuf.md'
-    - 'pwm' : 'modules/pwm.md'
-    - 'pwm2' : 'modules/pwm2.md'
-    - 'rfswitch' : 'modules/rfswitch.md'
-    - 'rotary' : 'modules/rotary.md'
-    - 'rtcfifo': 'modules/rtcfifo.md'
-    - 'rtcmem': 'modules/rtcmem.md'
-    - 'rtctime': 'modules/rtctime.md'
-    - 'si7021' : 'modules/si7021.md'
-    - 'sigma delta': 'modules/sigma-delta.md'
-    - 'sjson': 'modules/sjson.md'
-    - 'sntp': 'modules/sntp.md'
-    - 'softuart': 'modules/softuart.md'
-    - 'somfy': 'modules/somfy.md'
-    - 'spi': 'modules/spi.md'
-    - 'struct': 'modules/struct.md'
-    - 'switec': 'modules/switec.md'
-    - 'tcs34725': 'modules/tcs34725.md'
-    - 'tls': 'modules/tls.md'
-    - 'tm1829': 'modules/tm1829.md'
-    - 'tmr': 'modules/tmr.md'
-    - 'tsl2561': 'modules/tsl2561.md'
-    - 'u8g2': 'modules/u8g2.md'
-    - 'uart': 'modules/uart.md'
-    - 'ucg': 'modules/ucg.md'
-    - 'websocket': 'modules/websocket.md'
-    - 'wiegand': 'modules/wiegand.md'
-    - 'wifi': 'modules/wifi.md'
-    - 'wifi.monitor': 'modules/wifi_monitor.md'
-    - 'wps': 'modules/wps.md'
-    - 'ws2801': 'modules/ws2801.md'
-    - 'ws2812': 'modules/ws2812.md'
-    - 'ws2812-effects': 'modules/ws2812-effects.md'
-    - 'xpt2046': 'modules/xpt2046.md'
+  - Overview: 'index.md'
+  - Basics:
+      - Getting started: 'getting-started.md'
+      - Building the firmware: 'build.md'
+      - Flashing the firmware: 'flash.md'
+      - Uploading code: 'upload.md'
+      - Compiling code: 'compiling.md'
+      - Support: 'support.md'
+  - Reference:
+      - NodeMCU Language Reference Manual: 'nodemcu-lrm.md'
+      - Programming in NodeMCU: 'nodemcu-pil.md'
+  - FAQs:
+      - Lua Developer FAQ: 'lua-developer-faq.md'
+      - Extension Developer FAQ: 'extn-developer-faq.md'
+      - Hardware FAQ: 'hardware-faq.md'
+  - Whitepapers:
+      - Lua 5.3 Support: 'lua53.md'
+      - Lua Flash Store (LFS): 'lfs.md'
+      - Lua Compact Debug (LCD): 'lcd.md'
+      - Filesystem on SD card: 'sdcard.md'
+      - Internal filesystem: 'spiffs.md'
+  - Lua Modules:
+      - 'Lua modules directory': 'lua-modules/README.md'
+      - 'bh1750': 'lua-modules/bh1750.md'
+      - 'bme280': 'lua-modules/bme280.md'
+      - 'cohelper': 'lua-modules/cohelper.md'
+      - 'ds18b20': 'lua-modules/ds18b20.md'
+      - 'ds3231': 'lua-modules/ds3231.md'
+      - 'fifo': 'lua-modules/fifo.md'
+      - 'fifosock': 'lua-modules/fifosock.md'
+      - 'file_lfs': 'lua-modules/file_lfs.md'
+      - 'ftpserver': 'lua-modules/ftpserver.md'
+      - 'gossip': 'lua-modules/gossip.md'
+      - 'hdc1000': 'lua-modules/hdc1000.md'
+      - 'httpserver': 'lua-modules/httpserver.md'
+      - 'imap': 'lua-modules/imap.md'
+      - 'liquidcrystal': 'lua-modules/liquidcrystal.md'
+      - 'lm92': 'lua-modules/lm92.md'
+      - 'mcp23008': 'lua-modules/mcp23008.md'
+      - 'mcp23017': 'lua-modules/mcp23017.md'
+      - 'redis': 'lua-modules/redis.md'
+      - 'telnet': 'lua-modules/telnet.md'
+      - 'yeelink': 'lua-modules/yeelink.md'
+  - C Modules:
+      - 'adc': 'modules/adc.md'
+      - 'ads1115': 'modules/ads1115.md'
+      - 'adxl345': 'modules/adxl345.md'
+      - 'am2320': 'modules/am2320.md'
+      - 'apa102': 'modules/apa102.md'
+      - 'bit': 'modules/bit.md'
+      - 'bloom': 'modules/bloom.md'
+      - 'bme280': 'modules/bme280.md'
+      - 'bme280_math': 'modules/bme280_math.md'
+      - 'bme680': 'modules/bme680.md'
+      - 'bmp085': 'modules/bmp085.md'
+      - 'cjson': 'modules/cjson.md'
+      - 'coap': 'modules/coap.md'
+      - 'color-utils': 'modules/color-utils.md'
+      - 'cron': 'modules/cron.md'
+      - 'crypto': 'modules/crypto.md'
+      - 'dcc': 'modules/dcc.md'
+      - 'dht': 'modules/dht.md'
+      - 'encoder': 'modules/encoder.md'
+      - 'enduser setup / captive portal / WiFi manager': 'modules/enduser-setup.md'
+      - 'file': 'modules/file.md'
+      - 'gdbstub': 'modules/gdbstub.md'
+      - 'gpio': 'modules/gpio.md'
+      - 'hdc1080': 'modules/hdc1080.md'
+      - 'hmc5883l': 'modules/hmc5883l.md'
+      - 'http': 'modules/http.md'
+      - 'hx711': 'modules/hx711.md'
+      - 'i2c': 'modules/i2c.md'
+      - 'l3g4200d': 'modules/l3g4200d.md'
+      - 'mcp4725': 'modules/mcp4725.md'
+      - 'mdns': 'modules/mdns.md'
+      - 'mqtt': 'modules/mqtt.md'
+      - 'net': 'modules/net.md'
+      - 'node': 'modules/node.md'
+      - 'ow (1-Wire)': 'modules/ow.md'
+      - 'pcm': 'modules/pcm.md'
+      - 'perf': 'modules/perf.md'
+      - 'pipe': 'modules/pipe.md'
+      - 'pixbuf': 'modules/pixbuf.md'
+      - 'pwm': 'modules/pwm.md'
+      - 'pwm2': 'modules/pwm2.md'
+      - 'rfswitch': 'modules/rfswitch.md'
+      - 'rotary': 'modules/rotary.md'
+      - 'rtcfifo': 'modules/rtcfifo.md'
+      - 'rtcmem': 'modules/rtcmem.md'
+      - 'rtctime': 'modules/rtctime.md'
+      - 'si7021': 'modules/si7021.md'
+      - 'sigma delta': 'modules/sigma-delta.md'
+      - 'sjson': 'modules/sjson.md'
+      - 'sntp': 'modules/sntp.md'
+      - 'softuart': 'modules/softuart.md'
+      - 'somfy': 'modules/somfy.md'
+      - 'spi': 'modules/spi.md'
+      - 'struct': 'modules/struct.md'
+      - 'switec': 'modules/switec.md'
+      - 'tcs34725': 'modules/tcs34725.md'
+      - 'tls': 'modules/tls.md'
+      - 'tm1829': 'modules/tm1829.md'
+      - 'tmr': 'modules/tmr.md'
+      - 'tsl2561': 'modules/tsl2561.md'
+      - 'u8g2': 'modules/u8g2.md'
+      - 'uart': 'modules/uart.md'
+      - 'ucg': 'modules/ucg.md'
+      - 'websocket': 'modules/websocket.md'
+      - 'wiegand': 'modules/wiegand.md'
+      - 'wifi': 'modules/wifi.md'
+      - 'wifi.monitor': 'modules/wifi_monitor.md'
+      - 'wps': 'modules/wps.md'
+      - 'ws2801': 'modules/ws2801.md'
+      - 'ws2812': 'modules/ws2812.md'
+      - 'ws2812-effects': 'modules/ws2812-effects.md'
+      - 'xpt2046': 'modules/xpt2046.md'