Skip to content

Commit 2cdda76

Browse files
jfjlarosjfjlaros
committed
Restructured usage documentation.
1 parent 6639ad2 commit 2cdda76

File tree

5 files changed

+148
-154
lines changed

5 files changed

+148
-154
lines changed

‎README.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Arduino SimpleRPC Python client
1+
Arduino simpleRPC Python client
22
===============================
33

44
.. image:: https://img.shields.io/github/last-commit/jfjlaros/arduino-simple-rpc.svg
@@ -98,5 +98,5 @@ the :doc:`usage` section.
9898

9999

100100
.. _Arduino: https://www.arduino.cc
101-
.. _simpleRPC: https://simpleRPC.readthedocs.io/en/latest/index.html
102-
.. _ReadTheDocs: https://simpleRPC.readthedocs.io/en/latest/index.html
101+
.. _simpleRPC: https://simpleRPC.readthedocs.io
102+
.. _ReadTheDocs: https://arduino-simple-rpc.readthedocs.io

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@
77
introduction
88
install
99
usage
10+
library
1011
credits

‎docs/library.rst‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
Library
2+
=======
3+
4+
The API library provides the ``Interface`` class. A class instance is made by
5+
passing the path to a serial device to the constructor.
6+
7+
.. code:: python
8+
9+
>>> from simple_rpc import Interface
10+
>>>
11+
>>> interface = Interface('/dev/ttyACM0')
12+
13+
Every exported method will show up as a class method of the ``interface`` class
14+
instance. These methods can be used like any normal class methods.
15+
Alternatively, the exported methods can be called by name using the
16+
``call_method()`` function.
17+
18+
The constructor takes the following parameters.
19+
20+
.. list-table:: Constructor parameters.
21+
:header-rows: 1
22+
23+
* - name
24+
- optional
25+
- description
26+
* - ``device``
27+
- no
28+
- Serial device name.
29+
* - ``baudrate``
30+
- yes
31+
- Baud rate.
32+
* - ``wait``
33+
- yes
34+
- Time in seconds before communication starts.
35+
* - ``autoconnect``
36+
- yes
37+
- Automatically connect.
38+
39+
The following standard methods are available.
40+
41+
.. list-table:: Class methods.
42+
:header-rows: 1
43+
44+
* - name
45+
- description
46+
* - ``open()``
47+
- Connect to serial device.
48+
* - ``close()``
49+
- Disconnect from serial device.
50+
* - ``is_open()``
51+
- Query serial device state.
52+
* - ``call_method()``
53+
- Execute a method.
54+
55+
If the connection should not be made instantly, the ``autoconnect`` parameter
56+
can be used in combination with the ``open()`` function.
57+
58+
.. code:: python
59+
60+
>>> interface = Interface('/dev/ttyACM0', autoconnect=False)
61+
>>> # Do something.
62+
>>> interface.open()
63+
64+
The connection state can be queried using the ``is_open()`` function and it can
65+
be closed using the ``close()`` function.
66+
67+
.. code:: python
68+
69+
>>> if interface.is_open():
70+
>>> interface.close()
71+
72+
Additionally, the ``with`` statement is supported for easy opening and closing.
73+
74+
.. code:: python
75+
76+
>>> with Interface('/dev/ttyACM0') as interface:
77+
>>> interface.version()
78+
79+
The class instance has a public member variable named ``methods`` which
80+
contains the definitions of the exported methods.
81+
82+
.. code:: python
83+
84+
>>> interface.methods.keys()
85+
dict_keys(['inc', 'set_led'])
86+
>>> interface.methods['inc']
87+
{
88+
'return': {
89+
'doc': 'a + 1.',
90+
'fmt': '<h',
91+
'typename': 'int'},
92+
'doc': 'Increment a value.',
93+
'name': 'inc',
94+
'index': 2,
95+
'parameters': [
96+
{
97+
'doc': 'Value.',
98+
'name': 'a',
99+
'fmt': '<h',
100+
'typename': 'int'
101+
}
102+
]
103+
}
104+
105+
106+
Example
107+
-------
108+
109+
In our example we have exported the ``inc`` method, which is now present as a
110+
class method of the ``interface`` class instance.
111+
112+
.. code:: python
113+
114+
>>> interface.inc(1)
115+
2
116+
117+
Alternatively, the exported method can be called using the ``call_mathod()``
118+
function.
119+
120+
.. code:: python
121+
122+
>>> interface.call_method('inc', 1)
123+
2
124+
125+
To get more information about this class method, the built-in ``help()``
126+
function can be used.
127+
128+
.. code:: python
129+
130+
>>> help(interface.inc)
131+
Help on method inc:
132+
133+
inc(a) method of simple_rpc.simple_rpc.Interface instance
134+
Increment a value.
135+
136+
:arg int a: Value.
137+
138+
:returns int: a + 1.

‎docs/usage.rst‎

Lines changed: 4 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,5 @@
1-
Library
2-
=======
3-
4-
On the host, there are two ways to communicate with the device, either via the
5-
API library, or via the command line.
6-
7-
8-
API Library
9-
-----------
10-
11-
The API library provides the ``Interface`` class. A class instance is made by
12-
passing the path to a serial device to the constructor.
13-
14-
.. code:: python
15-
16-
>>> from simple_rpc import Interface
17-
>>>
18-
>>> interface = Interface('/dev/ttyACM0')
19-
20-
Every exported method will show up as a class method of the ``interface`` class
21-
instance. These methods can be used like any normal class methods.
22-
Alternatively, the exported methods can be called by name using the
23-
``call_method()`` function.
24-
25-
The constructor takes the following parameters.
26-
27-
.. list-table:: Constructor parameters.
28-
:header-rows: 1
29-
30-
* - name
31-
- optional
32-
- description
33-
* - ``device``
34-
- no
35-
- Serial device name.
36-
* - ``baudrate``
37-
- yes
38-
- Baud rate.
39-
* - ``wait``
40-
- yes
41-
- Time in seconds before communication starts.
42-
* - ``autoconnect``
43-
- yes
44-
- Automatically connect.
45-
46-
The following standard methods are available.
47-
48-
.. list-table:: Class methods.
49-
:header-rows: 1
50-
51-
* - name
52-
- description
53-
* - ``open()``
54-
- Connect to serial device.
55-
* - ``close()``
56-
- Disconnect from serial device.
57-
* - ``is_open()``
58-
- Query serial device state.
59-
* - ``call_method()``
60-
- Execute a method.
61-
62-
If the connection should not be made instantly, the ``autoconnect`` parameter
63-
can be used in combination with the ``open()`` function.
64-
65-
.. code:: python
66-
67-
>>> interface = Interface('/dev/ttyACM0', autoconnect=False)
68-
>>> # Do something.
69-
>>> interface.open()
70-
71-
The connection state can be queried using the ``is_open()`` function and it can
72-
be closed using the ``close()`` function.
73-
74-
.. code:: python
75-
76-
>>> if interface.is_open():
77-
>>> interface.close()
78-
79-
Additionally, the ``with`` statement is supported for easy opening and closing.
80-
81-
.. code:: python
82-
83-
>>> with Interface('/dev/ttyACM0') as interface:
84-
>>> interface.version()
85-
86-
The class instance has a public member variable named ``methods`` which
87-
contains the definitions of the exported methods.
88-
89-
.. code:: python
90-
91-
>>> interface.methods.keys()
92-
dict_keys(['inc', 'set_led'])
93-
>>> interface.methods['inc']
94-
{
95-
'return': {
96-
'doc': 'a + 1.',
97-
'fmt': '<h',
98-
'typename': 'int'},
99-
'doc': 'Increment a value.',
100-
'name': 'inc',
101-
'index': 2,
102-
'parameters': [
103-
{
104-
'doc': 'Value.',
105-
'name': 'a',
106-
'fmt': '<h',
107-
'typename': 'int'
108-
}
109-
]
110-
}
111-
112-
Example
113-
^^^^^^^
114-
115-
In our example we have exported the ``inc`` method, which is now present as a
116-
class method of the ``interface`` class instance.
117-
118-
.. code:: python
119-
120-
>>> interface.inc(1)
121-
2
122-
123-
Alternatively, the exported method can be called using the ``call_mathod()``
124-
function.
125-
126-
.. code:: python
127-
128-
>>> interface.call_method('inc', 1)
129-
2
130-
131-
To get more information about this class method, the built-in ``help()``
132-
function can be used.
133-
134-
.. code:: python
135-
136-
>>> help(interface.inc)
137-
Help on method inc:
138-
139-
inc(a) method of simple_rpc.simple_rpc.Interface instance
140-
Increment a value.
141-
142-
:arg int a: Value.
143-
144-
:returns int: a + 1.
145-
146-
147-
Command line interface
148-
----------------------
1+
Usage
2+
=====
1493

1504
The command line interface can be useful for method discovery and testing
1515
purposes. It currently has two subcommands: ``list``, which shows a list of
@@ -156,8 +10,9 @@ the ``-h`` option.
15610
15711
simple_rpc -h
15812
13+
15914
Example
160-
^^^^^^^
15+
-------
16116

16217
In our example, the ``list`` subcommand will show a description of the ``inc``
16318
method and the ``set_led`` method.

‎setup.cfg‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
[metadata]
22
name = arduino-simple-rpc
33
version = 1.0.3
4-
description = Simple RPC implementation for Arduino.
4+
description = Arduino SimpleRPC Python client.
55
long_description = file: README.rst
66
author = Jeroen F.J. Laros
77
author_email = jlaros@fixedpoint.nl
8-
url = https://github.com/jfjlaros/simpleRPC
8+
url = https://arduino-simple-rpc.readthedocs.io
99
keywords =
1010
license = MIT
1111
classifiers =

0 commit comments

Comments
 (0)