Updated documentation.

Author: jfjlaros

README.rst

@@ -1,5 +1,5 @@
-Arduino simpleRPC Python client
-===============================
+Arduino simpleRPC API client library and CLI
+============================================
 
 .. image:: https://img.shields.io/github/last-commit/jfjlaros/arduino-simple-rpc.svg
    :target: https://github.com/jfjlaros/arduino-simple-rpc/graphs/commit-activity
@@ -29,53 +29,35 @@ with the simpleRPC_ protocol. The exported method definitions are communicated
 to the host, which is then able to generate an API interface using this
 library.
 
-Only one function call is needed to perform a remote procedure call.
+Features:
+
+- User friendly API library.
+- Command line interface (CLI) for method discovery and testing.
+- Function and parameter names are defined on the Arduino.
+- API documentation is defined on the Arduino.
+- Support for disconnecting and reconnecting.
 
 Please see ReadTheDocs_ for the latest documentation.
 
 
 Quick start
 -----------
 
-Export any function e.g., ``digitalRead()`` and ``digitalWrite()`` using the
-``interface()`` function.
-
-.. code:: cpp
-
-    #include <simpleRPC.h>
-
-    void setup(void) {
-      Serial.begin(9600);
-    }
+Export any function e.g., ``digitalRead()`` and ``digitalWrite()`` on the
+Arduino, these functions will show up as member functions of the ``Interface``
+class instance.
 
-    void loop(void) {
-      interface(digitalRead, "", digitalWrite, "");
-    }
-
-These functions are now available on the host under name ``method2()`` and
-``method3()``.
+First, we make an ``Interface`` class instance and tell it to connect to the
+serial device ``/dev/ttyACM0``.
 
 .. code:: python
 
     >>> from simple_rpc import Interface
     >>> 
     >>> interface = Interface('/dev/ttyACM0')
-    >>> 
-    >>> interface.method2(8)
-    0
-    >>> interface.method3(13, True)
 
-The documentation string can be used to name and describe the method.
-
-.. code:: cpp
-
-    interface(
-      digitalRead,
-        "digital_read: Read digital pin. @pin: Pin number. @return: Pin value.",
-      digitalWrite,
-        "digital_write: Write to a digital pin. @pin: Pin number. @value: Pin value.");
-
-This is reflected on the host.
+We can use the built-in ``help()`` function to see the API documentation of any
+exported method.
 
 .. code:: python
 
@@ -89,12 +71,16 @@ This is reflected on the host.
 
         :returns int: Pin value.
 
-    >>> interface.digital_read(8)
+All exposed methods can be called like any other class method.
+
+.. code:: python
+
+    >>> interface.digital_read(8)         # Read from pin 8.
     0
-    >>> interface.digital_write(13, True)
+    >>> interface.digital_write(13, True) # Turn LED on.
 
 For more information about the host library and other interfaces, please see
-the :doc:`usage` section.
+the :doc:`usage` and :doc:`library` sections.
 
 
 .. _Arduino: https://www.arduino.cc

docs/introduction.rst

@@ -1,3 +1,16 @@
 Introduction
 ============
 
+This Python library provides a simple way to interface to Arduino_ functions
+exported with the simpleRPC_ protocol.
+
+For more background information and the reasons that led to this project, see
+the motivation_ section of the device library documentation.
+
+This project serves as a reference implementation for clients using the
+simpleRPC protocol.
+
+
+.. _Arduino: https://www.arduino.cc
+.. _motivation: https://simplerpc.readthedocs.io/en/latest/introduction.html#motivation
+.. _simpleRPC: https://simpleRPC.readthedocs.io

docs/library.rst

@@ -106,8 +106,9 @@ contains the definitions of the exported methods.
 Example
 -------
 
-In our example we have exported the ``inc`` method, which is now present as a
-class method of the ``interface`` class instance.
+In the example_ given in the device library documentation, the ``inc`` method
+is exported, which is now present as a class method of the ``Interface`` class
+instance.
 
 .. code:: python
 
@@ -136,3 +137,6 @@ function can be used.
         :arg int a: Value.
 
         :returns int: a + 1.
+
+
+.. _example: https://simplerpc.readthedocs.io/en/latest/usage_device.html#example

docs/usage.rst

@@ -14,8 +14,9 @@ the ``-h`` option.
 Example
 -------
 
-In our example, the ``list`` subcommand will show a description of the ``inc``
-method and the ``set_led`` method.
+If the Arduino has exposed the functions ``inc`` and ``set_led`` like in the
+example_ given in the device library documentation, the ``list`` subcommand
+will show the following.
 
 .. code::
 
@@ -37,9 +38,12 @@ method and the ``set_led`` method.
         int brightness: Brightness.
 
 
-A method can be called by using the ``call`` subcommand.
+Any of these methods can be called by using the ``call`` subcommand.
 
 .. code::
 
     $ simple_rpc call inc 1
     2
+
+
+.. _example: https://simplerpc.readthedocs.io/en/latest/usage_device.html#example

setup.cfg

@@ -1,7 +1,7 @@
 [metadata]
 name = arduino-simple-rpc
 version = 1.0.3
-description = Arduino SimpleRPC Python client.
+description = Arduino simpleRPC API client library and CLI.
 long_description = file: README.rst
 author = Jeroen F.J. Laros
 author_email = jlaros@fixedpoint.nl