Update RTD MkDocs (#3458)

.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

.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,48 +1,9 @@
-blockquote {
+/*https://github.com/mkdocs/mkdocs/issues/2538*/
-  padding: 0 15px;
+.wy-menu-vertical header,
-  color: #777;
+.wy-menu-vertical p.caption {
-  border-left: 4px solid #ddd;
+  color: #55a5d9;
-}
-
-.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 {
   font-size: 85%;
-  margin-right: 3px;
+  margin: 12px 0 0;
-}
-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;
 }
 
 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 {

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));
       });

docs/requirements.txt

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

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