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 {
+/*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;
 }

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,6 +4,8 @@ repo_url: https://github.com/nodemcu/nodemcu-firmware/
 
 theme:
   name: "readthedocs"
+  hljs_languages:
+    - lua
 strict: false
 
 markdown_extensions:
@@ -12,7 +14,6 @@ markdown_extensions:
   - 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