Update the sphinx doc.

docs/developer.rst

@@ -11,6 +11,15 @@ The source code is currently `available on GitHub`_ under the terms and
 conditions of the :ref:`MIT license <license>`. Fork away!
 
 
+Bug reports
+~~~~~~~~~~~
+
+To search for bugs or report them, please use the PyAX-12 Bug Tracker at:
+
+    https://github.com/jeremiedecock/pyax12/issues
+
+
+
 Contribute
 ~~~~~~~~~~
 
@@ -25,7 +34,8 @@ All contributions should at least comply with the following PEPs_:
 All contribution should be properly documented and tested with unittest_
 and/or doctest_.
 
-pylint_ and `pep8 <https://github.com/PyCQA/pep8>`__ should also be used to check the quality of each module.
+pylint_ and `pep8 <https://github.com/PyCQA/pep8>`__ should also be used to
+check the quality of each module.
 
 
 Changes

docs/intro.rst

@@ -1,5 +1,6 @@
 .. currentmodule:: pyax12
 
+============
 Introduction
 ============
 
@@ -19,16 +20,34 @@ PyAX-12 is an open source lightweight Python library to control
 
 
 Dependencies
-------------
+============
 
 -  Python >= 3.0
 -  `Python-serial`_
 
+PyAX-12 is tested to work with Python 3.4 under Gnu/Linux Debian 8 and Windows
+7.
+It should also work with Python 3.X under recent Gnu/Linux and Windows systems.
+It hasn't been tested (yet) on MacOSX and BSD systems.
+
+`Python-serial`_ is required to install PyAX-12.
+
+.. note::
+
+    If you use ``pip`` to install PyAX-12, Python-serial will be automatically
+    downloaded and installed (see the following install_ section).
+
+
+.. _install:
 
 Installation
-------------
+============
+
+Gnu/Linux
+---------
 
-You can install, upgrade, uninstall PyAX-12 with these commands::
+You can install, upgrade, uninstall PyAX-12 with these commands (in a
+terminal)::
 
     pip install pyax12
     pip install --upgrade pyax12
@@ -42,22 +61,51 @@ Or, if you have downloaded the PyAX-12 source code::
 .. 
 ..     sudo apt-get install pyax12
 
+Windows
+-------
+
+.. note::
+
+    The following installation procedure has been tested to work with Python
+    3.4 under Windows 7.
+    It should also work with recent Windows systems.
+
+You can install, upgrade, uninstall PyAX-12 with these commands (in a
+`command prompt`_)::
+
+    py -m pip install pyax12
+    py -m pip install --upgrade pyax12
+    py -m pip uninstall pyax12
+
+Or, if you have downloaded the PyAX-12 source code::
+
+    py setup.py install
 
 Example usage
--------------
+=============
+
+.. Please check whether the serial port, the baudrate and the
+.. Dynamixel IDs defined in the following examples fits with your hardware.
 
-Many examples are available in the examples_ directory.
+In the following examples, the ``dynamixel_id``, ``port`` and ``baudrate``
+values should be adapted depending on your configuration:
 
-The `port` and `baudrate` values should be adapted depending on your
-configuration.
+- for Linux users the `port` value should be something like
+
+  - "/dev/ttyS0", "/dev/ttyS1", ... if you use an actual serial port
+  - "/dev/ttyUSB0", "/dev/ttyUSB1", ... if you use an `USB to serial` adapter
+    (like the USB2Dynamixel_ adapter)
 
-For Linux users the `port` value should be something like "/dev/ttyS0" or
-"/dev/ttyUSB0".
+- for Windows users the `port` value should be something like "COM2", "COM3",
+  ...
 
-For Windows users the `port` value should be something like "COM1", "COM2", ...
+If you use the USB2Dynamixel_ device, make sure its switch is set on
+"TTL".
+
+Some other examples are available in the examples_ directory.
 
 Ping a Dynamixel
-~~~~~~~~~~~~~~~~
+----------------
 
 ::
 
@@ -66,8 +114,10 @@ Ping a Dynamixel
     # Connect to the serial port
     serial_connection = Connection(port="/dev/ttyUSB0", baudrate=57600)
 
+    dynamixel_id = 3
+
     # Ping the third dynamixel unit
-    is_available = serial_connection.ping(3)
+    is_available = serial_connection.ping(dynamixel_id)
 
     print(is_available)
 
@@ -76,7 +126,7 @@ Ping a Dynamixel
 
 
 Scan (search available Dynamixel units)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
 
 ::
 
@@ -96,7 +146,7 @@ Scan (search available Dynamixel units)
 
 
 Print the control table of the third Dynamixel unit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------
 
 ::
 
@@ -105,15 +155,17 @@ Print the control table of the third Dynamixel unit
     # Connect to the serial port
     serial_connection = Connection(port="/dev/ttyUSB0", baudrate=57600)
 
+    dynamixel_id = 3
+
     # Print the control table of the specified Dynamixel unit
-    serial_connection.pretty_print_control_table(3)
+    serial_connection.pretty_print_control_table(dynamixel_id)
 
     # Close the serial connection
     serial_connection.close()
 
 
 Move the first Dynamixel unit to 0° then go to 300° and finally go back to 150°
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------------------------------------
 
 ::
 
@@ -122,20 +174,22 @@ Move the first Dynamixel unit to 0° then go to 300° and finally go back to 150
     # Connect to the serial port
     serial_connection = Connection(port="/dev/ttyUSB0", baudrate=57600)
 
+    dynamixel_id = 1
+
     # Goto to 0°
-    serial_connection.goto(1, 0, degrees=True)
+    serial_connection.goto(dynamixel_id, 0, degrees=True)
 
     # Wait 2 seconds
     time.sleep(2)
 
     # Go back to 300°
-    serial_connection.goto(1, 300, degrees=True)
+    serial_connection.goto(dynamixel_id, 300, degrees=True)
 
     # Wait 2 seconds
     time.sleep(2)
 
     # Go back to 150°
-    serial_connection.goto(1, 150, degrees=True)
+    serial_connection.goto(dynamixel_id, 150, degrees=True)
 
     # Close the serial connection
     serial_connection.close()
@@ -145,7 +199,7 @@ Move the first Dynamixel unit to 0° then go to 300° and finally go back to 150
 .. _related-libraries:
 
 Related libraries
------------------
+=================
 
 Other libraries to control
 `Dynamixel AX-12+ <http://www.robotis.com/xe/dynamixel_en>`__
@@ -162,6 +216,9 @@ actuators are referenced in the following (non comprehensive) list:
 
 .. _Dynamixel AX-12+ actuators: http://www.robotis.com/xe/dynamixel_en
 .. _examples: https://github.com/jeremiedecock/pyax12/tree/master/examples
+.. _USB2Dynamixel: http://support.robotis.com/en/product/auxdevice/interface/usb2dxl_manual.htm
+.. _Python-serial: http://pyserial.sourceforge.net
+.. _command prompt: https://en.wikipedia.org/wiki/Cmd.exe
 
 .. _PyPot: https://github.com/poppy-project/pypot
 .. _Pydyn: https://github.com/humm/pydyn