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%;
-}
-.wy-plain-list-disc, .rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {
-  line-height: 20px;
-  margin-bottom: 16px;
+  margin: 12px 0 0;
 }

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,36 +4,37 @@ 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:
+  #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:
+  - 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:
+  - FAQs:
       - Lua Developer FAQ: 'lua-developer-faq.md'
       - Extension Developer FAQ: 'extn-developer-faq.md'
-- Whitepapers:
+  - Whitepapers:
       - Filesystem on SD card: 'sdcard.md'
       - Writing external C modules: 'modules/extmods.md'
-- C Modules:
+  - C Modules:
       - 'adc': 'modules/adc.md'
       - 'bit': 'modules/bit.md'
       - 'bthci': 'modules/bthci.md'