From 78ccb44a90584387dba6cfbdaa19fb651a6f64ab Mon Sep 17 00:00:00 2001
From: Radomir Dopieralski <openstack@sheep.art.pl>
Date: Tue, 26 May 2015 23:34:31 +0200
Subject: [PATCH] docs: Document esp module for ESP8266.

I document as much as I could guess from experiments and reading the
code for the ``esp`` module for the ESP8266 port of Micropython.

For now the tag has to be set manually with -t option when building,
when we have properly split documentation, there will be a separate
config file for esp8266 with that the tag "port_esp8266" set.

To build use:

make SPHINXOPTS="-t port_esp8266" html
---
 docs/library/esp.rst        | 56 +++++++++++++++++++++++++
 docs/library/esp.socket.rst | 82 +++++++++++++++++++++++++++++++++++++
 docs/library/index.rst      | 12 ++++++
 3 files changed, 150 insertions(+)
 create mode 100644 docs/library/esp.rst
 create mode 100644 docs/library/esp.socket.rst

diff --git a/docs/library/esp.rst b/docs/library/esp.rst
new file mode 100644
index 0000000000..8dd39f536f
--- /dev/null
+++ b/docs/library/esp.rst
@@ -0,0 +1,56 @@
+:mod:`esp` --- functions related to the ESP8266
+===============================================
+
+.. module:: esp
+    :synopsis: functions related to the ESP8266
+
+The ``esp`` module contains specific functions related to the ESP8266 module.
+
+
+Functions
+---------
+
+.. function:: connect(ssid, password)
+
+    Connect to the specified wireless network, using the specified password.
+
+.. function:: disconnect()
+
+    Disconnect from the currently connected wireless network.
+
+.. function:: scan(cb)
+
+    Initiate scanning for the available wireless networks.
+
+    Once the scanning is complete, the provided callback function ``cb`` will
+    be called once for each network found, and passed a tuple with information
+    about that network.
+
+.. function:: status()
+
+    Return the current status of the wireless connection.
+
+    The possible statuses are defined as constants:
+
+        * ``STAT_IDLE`` -- no connection and no activity,
+        * ``STAT_CONNECTING`` -- connecting in progress,
+        * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password,
+        * ``STAT_NO_AP_FOUND`` -- failed because no access point replied,
+        * ``STAT_CONNECT_FAIL`` -- failed due to other problems,
+        * ``STAT_GOT_IP`` -- connection susccessful.
+
+.. function:: getaddrinfo((hostname, port, lambda))
+
+    Initiate resolving of the given hostname.
+
+    When the hostname is resolved, the provided ``lambda`` callback will be
+    called with two arguments, first being the hostname being resolved,
+    second a tuple with information about that hostname.
+
+Classes
+-------
+
+.. toctree::
+    :maxdepth: 1
+
+    esp.socket.rst
diff --git a/docs/library/esp.socket.rst b/docs/library/esp.socket.rst
new file mode 100644
index 0000000000..4f5234a154
--- /dev/null
+++ b/docs/library/esp.socket.rst
@@ -0,0 +1,82 @@
+class socket -- network socket
+==============================
+
+``socket`` is an object that represents a network socket. Example usage::
+
+    socket = esp.socket()
+    socket.onrecv(print)
+    socket.connect(('207.58.139.247', 80))
+    socket.send('GET /testwifi/index.html HTTP/1.0\r\n\r\n')
+
+Constructors
+------------
+
+.. class:: esp.socket()
+
+    Create and return a socket object.
+
+
+TCP Methods
+-----------
+
+.. method:: socket.connect(addr)
+
+    Connect to the adress and port specified in the ``addr`` tuple.
+
+.. method:: socket.close()
+
+    Close the connection.
+
+.. method:: socket.accept()
+
+    Accept a single connection from the connection queue.
+
+.. method:: socket.listen(backlog)
+
+    Start listening for incoming connections.
+
+    Note: Only one socket can be listening for connections at a time.
+
+.. method:: socket.bind(addr)
+
+    Bind the socket to the address and port specified by the ``addr`` tuple.
+
+.. method:: socket.send(buf)
+
+    Send the bytes from ``buf``.
+
+.. method:: socket.recv()
+
+    Receive and return bytes from the socket.
+
+
+UDP Methods
+-----------
+
+.. method:: socket.sendto(data, addr)
+
+    Placeholder for UDP support, not implemented yet.
+
+.. method:: socket.recvfrom(addr)
+
+    Placeholder for UDP support, not implemented yet.
+
+
+Callback Setter Methods
+-----------------------
+
+.. method:: onconnect(lambda)::
+
+    When connection is established, call the callback ``lambda``.
+
+.. method:: onrecv(lambda)::
+
+    When data is received, call the callback ``lambda``.
+
+.. method:: onsent(lamda)::
+
+    What data is finished sending, call the callback ``lambda``.
+
+.. method:: ondisconnect(lambda)::
+
+    Call the callback ``lambda`` when the connection is closed.
diff --git a/docs/library/index.rst b/docs/library/index.rst
index b5a7b3ca9c..9b77271814 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -65,3 +65,15 @@ The following libraries are specific to the pyboard.
 
    pyb.rst
    network.rst
+
+.. only:: port_esp8266
+
+    Libraries specific to the ESP8266
+    ---------------------------------
+
+    The following libraries are specific to the ESP8266.
+
+    .. toctree::
+       :maxdepth: 2
+
+       esp.rst