diff --git a/.gitignore b/.gitignore index a99b8a5a..d820c77c 100644 --- a/.gitignore +++ b/.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 diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..983ee9b1 --- /dev/null +++ b/.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 diff --git a/docs/css/extra.css b/docs/css/extra.css index dbe505ae..a5e31057 100644 --- a/docs/css/extra.css +++ b/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; + 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; -} \ No newline at end of file diff --git a/docs/img/favicon.ico b/docs/img/favicon.ico new file mode 100644 index 00000000..04011552 Binary files /dev/null and b/docs/img/favicon.ico differ diff --git a/docs/js/extra.js b/docs/js/extra.js index 3a18ada8..2653f4a7 100644 --- a/docs/js/extra.js +++ b/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)); }); diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..c2e8755b --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +mkdocs==1.2.2 diff --git a/mkdocs.yml b/mkdocs.yml index 37ff0aaf..3ca7334f 100644 --- a/mkdocs.yml +++ b/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'