docs: convert md to rst, add readthedocs

Author: igrr

doc/.gitignore

@@ -0,0 +1 @@
+_build

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = ESP8266ArduinoCore
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/Troubleshooting/debugging.md

@@ -0,0 +1,107 @@
+Debugging
+=========
+
+Introduction
+------------
+
+Since 2.1.0-rc1 the core includes a Debugging feature that is
+controllable over the IDE menu.
+
+The new menu points manage the real-time Debug messages.
+
+Requirements
+~~~~~~~~~~~~
+
+For usage of the debugging a Serial connection is required (Serial or
+Serial1).
+
+The Serial Interface need to be initialized in the ``setup()``.
+
+Set the Serial baud rate as high as possible for your Hardware setup.
+
+Minimum sketch to use debugging:
+
+.. code:: cpp
+
+    void setup() {
+        Serial.begin(115200);
+    }
+
+    void loop() {
+    }
+
+Usage
+~~~~~
+
+1. Select the Serial interface for the Debugging messages: |Debug-Port|
+
+2. Select which type / level you want debug messages for: |Debug-Level|
+
+3. Check if the Serial interface is initialized in ``setup()`` (see
+   `Requirements <#requirements>`__)
+
+4. Flash sketch
+
+5. Check the Serial Output
+
+Informations
+------------
+
+It work with every sketch that enables the Serial interface that is
+selected as debug port.
+
+The Serial interface can still be used normal in the Sketch.
+
+The debug output is additional and will not disable any interface from
+usage in the sketch.
+
+For Developers
+~~~~~~~~~~~~~~
+
+For the debug handling uses defines.
+
+The defined are set by command line.
+
+Debug Port
+^^^^^^^^^^
+
+The port has the define ``DEBUG_ESP_PORT`` possible value: - Disabled:
+define not existing - Serial: Serial - Serial1: Serial1
+
+Debug Level
+^^^^^^^^^^^
+
+All defines for the different levels starts with ``DEBUG_ESP_``
+
+a full list can be found here in the
+`boards.txt <https://github.com/esp8266/Arduino/blob/master/boards.txt#L180>`__
+
+Example for own debug messages
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The debug messages will be only shown when the Debug Port in the IDE
+menu is set.
+
+.. code:: cpp
+
+    #ifdef DEBUG_ESP_PORT
+    #define DEBUG_MSG(...) DEBUG_ESP_PORT.printf( __VA_ARGS__ )
+    #else
+    #define DEBUG_MSG(...) 
+    #endif
+
+    void setup() {
+        Serial.begin(115200);
+        
+        delay(3000);
+        DEBUG_MSG("bootup...\n");
+    }
+
+    void loop() {
+        DEBUG_MSG("loop %d\n", millis());
+        delay(1000);
+    }
+
+.. |Debug-Port| image:: debug_port.png
+.. |Debug-Level| image:: debug_level.png
+

doc/Troubleshooting/debugging.rst

@@ -0,0 +1,65 @@
+Stack Dumps
+===========
+
+Introduction
+------------
+
+If the ESP crash the Exception Cause will be shown and the current stack will be dumped.
+
+Example:
+
+::
+
+    Exception (0): epc1=0x402103f4 epc2=0x00000000 epc3=0x00000000 excvaddr=0x00000000 depc=0x00000000
+
+    ctx: sys 
+    sp: 3ffffc10 end: 3fffffb0 offset: 01a0
+
+    >>>stack>>>
+    3ffffdb0:  40223e00 3fff6f50 00000010 60000600  
+    3ffffdc0:  00000001 4021f774 3fffc250 4000050c  
+    3ffffdd0:  400043d5 00000030 00000016 ffffffff  
+    3ffffde0:  400044ab 3fffc718 3ffffed0 08000000  
+    3ffffdf0:  60000200 08000000 00000003 00000000  
+    3ffffe00:  0000ffff 00000001 04000002 003fd000  
+    3ffffe10:  3fff7188 000003fd 3fff2564 00000030  
+    3ffffe20:  40101709 00000008 00000008 00000020  
+    3ffffe30:  c1948db3 394c5e70 7f2060f2 c6ba0c87  
+    3ffffe40:  3fff7058 00000001 40238d41 3fff6ff0  
+    3ffffe50:  3fff6f50 00000010 60000600 00000020  
+    3ffffe60:  402301a8 3fff7098 3fff7014 40238c77  
+    3ffffe70:  4022fb6c 40230ebe 3fff1a5b 3fff6f00  
+    3ffffe80:  3ffffec8 00000010 40231061 3fff0f90  
+    3ffffe90:  3fff6848 3ffed0c0 60000600 3fff6ae0  
+    3ffffea0:  3fff0f90 3fff0f90 3fff6848 3fff6d40  
+    3ffffeb0:  3fff28e8 40101233 d634fe1a fffeffff  
+    3ffffec0:  00000001 00000000 4022d5d6 3fff6848  
+    3ffffed0:  00000002 4000410f 3fff2394 3fff6848  
+    3ffffee0:  3fffc718 40004a3c 000003fd 3fff7188  
+    3ffffef0:  3fffc718 40101510 00000378 3fff1a5b  
+    3fffff00:  000003fd 4021d2e7 00000378 000003ff  
+    3fffff10:  00001000 4021d37d 3fff2564 000003ff  
+    3fffff20:  000003fd 60000600 003fd000 3fff2564  
+    3fffff30:  ffffff00 55aa55aa 00000312 0000001c  
+    3fffff40:  0000001c 0000008a 0000006d 000003ff  
+    3fffff50:  4021d224 3ffecf90 00000000 3ffed0c0  
+    3fffff60:  00000001 4021c2e9 00000003 3fff1238  
+    3fffff70:  4021c071 3ffecf84 3ffecf30 0026a2b0  
+    3fffff80:  4021c0b6 3fffdab0 00000000 3fffdcb0  
+    3fffff90:  3ffecf40 3fffdab0 00000000 3fffdcc0  
+    3fffffa0:  40000f49 40000f49 3fffdab0 40000f49  
+    <<<stack<<<
+
+The first number after ``Exception`` gives the cause of the reset. a
+full ist of all causes can be found `here <../exception_causes.md>`__
+the hex after are the stack dump.
+
+Decode
+~~~~~~
+
+It's possible to decode the Stack to readable information. For more info see the `Esp Exception Decoder <https://github.com/me-no-dev/EspExceptionDecoder>`__ tool.
+
+.. figure:: ESP_Exception_Decoderp.png
+   :alt: ESP Exception Decoder
+
+   ESP Exception Decoder