Merge pull request #24 from sonelu/revert-23-documentation

Revert "Documentation updates"

README.md

@@ -1,10 +1,9 @@
-# Roboglia
-
-[![PyPI version](https://badge.fury.io/py/roboglia.svg)](https://badge.fury.io/py/roboglia)
 [![Build Status](https://travis-ci.com/sonelu/roboglia.svg?branch=master)](https://travis-ci.com/sonelu/roboglia)
 [![Documentation Status](https://readthedocs.org/projects/roboglia/badge/?version=latest)](https://roboglia.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/sonelu/roboglia/branch/master/graph/badge.svg)](https://codecov.io/gh/sonelu/roboglia)
 
+# Roboglia
+
 ``roboglia`` is a framework that helps developers with the setup of robots
 in a more reusable fashion. Most of the times the creation of robots involve
 integrating actuators, sensors, cameras and microphones, periodically accessing
@@ -13,7 +12,7 @@ activities.
 
 The name `roboglia` is derived from the glial cells present in the brian.
 Their role is to support the neurons' functions by supplying them
-with nutrients, energy and disposing of waste. The analogy is that ``roboglia``
+with nutirients, energy and disposing of waste. The analogy is that ``roboglia``
 provides this boring, but very complex activity of putting together the specific
 functions of the physical devices used in robots in order to provide a more
 accessible high-level representation of the robot for the use of the "smart"
@@ -26,17 +25,7 @@ rather than gritty details.
 
 ## Installation
 
-You can install roboglia with ``pip``:
-
-    pip install roboglia
-
-This will only install ``roboglia`` and core dependencies without any
-hardware communication dependencies. If you need to install any of them
-you have to use the **extra`** installation option like this:
-
-    pip install roboglia[dynamixel]
-
-Please read carefully the installation instructions from the
+Please read carefully the installation instrcutions from the
 [documentation](https://roboglia.readthedocs.io/en/latest/install.html).
 As ``roboglia`` needs to interact with a lot of hardware devices, it is very
 sensitive to the platform and OS version used. The documentation provides more
@@ -55,25 +44,25 @@ There is also an epub version that can be accessed
 ## Contribution
 
 We are very receptive for contributions. Please clone the repository and
-submit pull requests with the desired contribution. They will be moderated and,
+sumbit pull requests with the desired contrbution. They will be moderated and,
 if they add values to the users, they will be integrated. Please note that
 the [Travis CI](https://travis-ci.com) integration will perform the following
 two tests on the pull requests:
 
-* it will run all automated tests defined in ``tests.py`` file using
-  ``pytest``. Please make sure that you also run them **before** submitting
-  the pull request to avoid it failing. You you should install first your
-  version of the package on your machine an then run the tests like this
-  (you should be in the top directory of the cloned repository):
+* it will run all automated tests located in ``tests/`` folder. Please make
+  sure that you also run them **before** submitting the pull request to avoid
+  it failing. You you should install first your version of the package on
+  your machine an then run the tests like this (you should be in the top
+  directory of the cloned repository):
 
       sudo python setup.py install
       cd tests
-      python all_tests.py
+      pyton all_tests.py
 
   Make sure that there are no errors issued by the unit tests. If you created
   new classes or new functions that are not covered by testing, then you will
   also need to write a test class or add a test method in an exiting class
-  to test that functionality and submit those changes too.
+  to test that functionlity and submit those changes too.
 
 * it will check PEP8 on the Python code using flake8. You should install
   (if you don't have it already) on your machine and run this (from the
@@ -94,7 +83,7 @@ in the pull request.
 
 If you create new Python files please add the copyright comments as they are
 included in the other files. Make sure you update your name at the top, we want
-people to receive the credit for their work. Similarly, if you change an
+people to recieve the creadit for their work. Similarly, if you change an
 existing file feel free to add your name at the top of the file.
 
 ## Showcasing your robot
@@ -103,7 +92,7 @@ If you use ``roboglia`` in your project we will like to hear about it and
 we will showcase it on this page. Please
 [open an issue](https://github.com/sonelu/roboglia/issues/new) with title
 "Showcase of robot" and provide us with information about your robot. You can
-send us links to the documentation or code of the robot and one picture
+send us links to the documentaion or code of the robot and one picture
 (link to an public one) that we could use in the showcase. If you want to
 provide an email address for contact we will be more than happy to include
 that too.

docs/install.rst

@@ -4,139 +4,124 @@ Installation
 Requirements
 ------------
 
-``roboglia`` requires Python 3. The CI builds test the package with:
-
-- Python **3.6** and **3.7**
-- OS: **Linux**; distributions **Xenial** (16.04) and **Bionic** (18.04)
-- Architecture: **AMD64** and **ARM64**
-
-This doesn't mean the package might not work on other OS / Architecture /
-Python version combinations, but they are not officially supported.
+``roboglia`` requires Python 3.
 
 Due to the heavily hardware dependent nature of ``roboglia`` some of the
-functionality requires lower level modules to communicate with the
+functionality requires lower level modules needed to communicate with the
 physical devices. For example to use Dynamixel devices you need ``dynamixel_sdk``
-module, for I2C devices ``smbus2``, for SPI devices ``spidev``, etc. These
-packages are not available for all platforms and Python version, so care
+module, for I2C devices ``smbus2``, for SPI devices ``spidev``. These
+packages are not available for all platforms and Phyton version, so care
 must be taken when deciding what platform to use for the robot.
 
 While the package includes these functionalities, we are aware that not
 all robots will need to use all these types of devices. For instance,
 a robot might use only PWM controlled devices accessed through an I2C
 multiplexer like this `16 Channel PWM Bonnet`_ from Adafruit.
-There is therefore no need to install ``dynamixel_sdk`` or ``spidev``.
+There is therefore no need to install ``dynamixel_sdk`` which is a relatively
+complex activity.
 
 With this observation in mind we have decided not to explicitly include
 dependencies on these low level packages. This means that when you will install
 ``roboglia`` it will not automatically install them for you. It will also
-not check if they are available, instead it will be your responsibility
+not check if they are avaialable, instead it will be your responsiblity
 to install the dependencies as you need them, as explained in the next
-paragraphs. This is an important point to remember, so here it is emphasized
+paragraphs. This is an important point to remember, so here it is emphasised
 in a warning:
 
 .. warning::
-
-    ``roboglia`` does not automatically install dependent packages for
+    ``roboglia`` does not automatically install  dependent packages for
     hardware access. You will have to install them manually as your
-    robot requires.
-
-Installation procedure
-----------------------
-
-You can install ``roboglia`` without installing previously the hardware
-dependencies, but when you will use it you must have those dependencies
-available otherwise Python will raise an ``No module`` exception.
+    robot require.
 
-You can install ``roboglia`` using pip::
+dynamixel_sdk
+^^^^^^^^^^^^^
 
-    pip install roboglia
+You will need to install ``dynamixel_sdk`` if you plan to use any Dynamixel
+devices or use any of the class in the module ``roboglia.dynamixel``.
 
-This will work well, and is especially recommended, for `conda`_ environments.
-This will install only the main package without hardware package dependencies,
-but with other dependencies (like ``PyYAML``).
+The `dynamixel_sdk`_ is released and maintained by ROBOTIS, the maker of 
+the Dynamixel ecosystem. The installation requires running ``setuptools``
+and is not avaialable in ``pip``.
 
-If you want to install a particular version of the package you can specify::
-
-    pip install roboglia==X.X.X
-
-If you want to install the latest code from Github, you can clone it and
-install it from there::
+The installation procedure involves downloading the package from Github and
+installing it manually. The following instructions are for Linux and MacOS,
+although they are very similiar for Windows::
 
     cd /tmp
-    git clone https://github.com/sonelu/roboglia.git
-    cd roboglia
+    git clone https://github.com/ROBOTIS-GIT/DynamixelSDK.git
+    cd DynamixelSDK/python
     sudo python setup.py install
 
 The last command might require you to enter the password to allow ``sudo`` elevation.
+Depending on your platform settings you might be able to run the last command
+without ``sudo``.
 
-Installing hardware dependencies
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The installer comes with a number of configurations for **extra** packages that
-can be installed as needed.
+If you plan to use virtual environments or ``conda`` make sure that you
+first activate the environment where you want to install ``dynamixel_sdk``.
 
-`dynamixel_sdk`_ is released and maintained by ROBOTIS, the maker of 
-the Dynamixel ecosystem. For more details about the package and up to date 
-information and installation instructions visit the `DynamixelSDK Manual`_ 
-on ROBOTIS website.
-
-To install ``dynamixel_sdk`` when you install ``roboglia`` you specify::
-
-    pip install roboglia[dynamixel]
+For more details about the package and up to date information and installation
+instructions visit the `DynamixelSDK Manual`_ on ROBOTIS website.
 
-.. warning::
+smbus2
+^^^^^^
 
-    ``dynamixel_sdk`` is itself dependent on ``pyserial`` and will attempt to
-    install it. Not all platforms have support for ``pyserial``.
+``roboglia`` uses ``smbus2`` to operate I2C devices. Therefore, if your robot
+will need to access these types of devices you will need to install this
+package.
 
+Fortunatelly this is simple and can be done with ``pip`` as follows::
 
-If you plan to use ``I2C`` devices in your robot, then you need to install
-``smbus2``::
+    pip install smbus2
 
-    pip install roboglia[i2c]
+If you plan to use virtual environments or ``conda`` make sure that you
+first activate the environment where you want to install ``smbus2``.
 
 For more details about the package and up to date information and installation
 instructions visit the `smbus2 Github`_ page.
 
-.. warning::
-
-    Not all platforms have support for ``smbus2``.
-
-If you plan to use ``SPI`` devices in your robot, then you need to install
-``spidev``::
 
-    pip install roboglia[spi]
+spidev
+^^^^^^
 
-For more details about the package and up to date information and installation
-instructions visit the `spidev Github`_ page.
+``roboglia`` uses ``spidev`` to operate SPI devices. Therefore, if your robot
+will need to access these types of devices you will need to install this
+package.
 
-.. warning::
+Fortunatelly this is simple and can be done with ``pip`` as follows::
 
-    Not all platforms have support for ``spidev``.
+    pip install spidev
 
-If you intend to use a combination of hardware you can install them by
-entering the codes above separated by comas, for instance if you need
-Dynamixel and I2C you would use::
+If you plan to use virtual environments or ``conda`` make sure that you
+first activate the environment where you want to install ``spidev``.
 
-    pip install roboglia[dynamixel,i2c]
+For more details about the package and up to date information and installation
+instructions visit the `spidev Github`_ page.
 
-.. warning::
+.. warning:
+    ``spidev`` might not work on all platforms and is highly dependent on 
+    the operating system and the configuration of the machine.
 
-    The ``pip`` syntax requires there are no blanks between the elements in
-    the square brackets above.
+Installation procedure
+----------------------
 
-To simplify things, if you need **all** communication packages there is an option
-``all`` that you can use in the installation::
+You can install ``roboglia`` without installing previously the hardware
+dependencies, but when you will use it you must have those dependencies
+available otherwise Python will raise an ``No module`` exception.
 
-    pip install roboglia[all]
+For the time being the installation is manual. You will have to download
+the package from Github and install it using the setup script provided::
 
-.. note::
+    cd /tmp
+    git clone https://github.com/sonelu/roboglia.git
+    cd roboglia
+    sudo python setup.py install
 
-    This option will be kept in line with future developments and, if new
-    hardware dependencies will be added, will be updated to include them.
-    So you can be assured that this installation option will install **all**
-    extra dependencies in addition to the core dependencies.
+The last command might require you to enter the password to allow ``sudo`` elevation.
+Depending on your platform settings you might be able to run the last command
+without ``sudo``.
 
+If you plan to use virtual environments or ``conda`` make sure that you
+first activate the environment where you want to install ``dynamixel_sdk``.
 
 References
 ----------
@@ -147,5 +132,4 @@ References
 .. _`dynamixel_sdk`: https://github.com/ROBOTIS-GIT/DynamixelSDK
 .. _`DynamixelSDK Manual`: https://github.com/ROBOTIS-GIT/DynamixelSDK.git
 .. _`smbus2 Github`: https://github.com/kplindegaard/smbus2
-.. _`spidev Github`: https://github.com/doceme/py-spidev
-.. _`conda`: https://www.anaconda.com
+.. _`spidev Github`: https://github.com/doceme/py-spidev

docs/reference/base/roboglia.base.BaseDevice.rst

@@ -18,7 +18,6 @@ roboglia.base.BaseDevice
       ~BaseDevice.get_model_path
       ~BaseDevice.open
       ~BaseDevice.read_register
-      ~BaseDevice.register_by_address
       ~BaseDevice.write_register
 
 
@@ -49,7 +48,6 @@ roboglia.base.BaseDevice
    .. automethod:: get_model_path
    .. automethod:: open
    .. automethod:: read_register
-   .. automethod:: register_by_address
    .. automethod:: write_register
 
 

docs/reference/base/roboglia.base.BaseRobot.rst

@@ -13,7 +13,6 @@ roboglia.base.BaseRobot
    .. autosummary::
 
       ~BaseRobot.__init__
-      ~BaseRobot.device_by_id
       ~BaseRobot.from_yaml
       ~BaseRobot.start
       ~BaseRobot.stop
@@ -30,7 +29,6 @@ roboglia.base.BaseRobot
       ~BaseRobot.devices
       ~BaseRobot.groups
       ~BaseRobot.joints
-      ~BaseRobot.name
       ~BaseRobot.syncs
 
 
@@ -42,7 +40,6 @@ roboglia.base.BaseRobot
 
 
    .. automethod:: __init__
-   .. automethod:: device_by_id
    .. automethod:: from_yaml
    .. automethod:: start
    .. automethod:: stop

docs/reference/dynamixel.rst

@@ -4,7 +4,7 @@
 
 .. automodule:: roboglia.dynamixel
 
-This module contains classes that are specific for interaction with I2C
+This module contains classes that are specific for interation with dynamixel
 devices.
 
 *Buses*

docs/reference/dynamixel/roboglia.dynamixel.DynamixelBus.rst

@@ -14,7 +14,6 @@ roboglia.dynamixel.DynamixelBus
 
       ~DynamixelBus.__init__
       ~DynamixelBus.close
-      ~DynamixelBus.from_dict
       ~DynamixelBus.open
       ~DynamixelBus.ping
       ~DynamixelBus.read
@@ -49,7 +48,6 @@ roboglia.dynamixel.DynamixelBus
 
    .. automethod:: __init__
    .. automethod:: close
-   .. automethod:: from_dict
    .. automethod:: open
    .. automethod:: ping
    .. automethod:: read

docs/reference/dynamixel/roboglia.dynamixel.DynamixelDevice.rst

@@ -18,8 +18,6 @@ roboglia.dynamixel.DynamixelDevice
       ~DynamixelDevice.get_model_path
       ~DynamixelDevice.open
       ~DynamixelDevice.read_register
-      ~DynamixelDevice.register_by_address
-      ~DynamixelDevice.register_low_endian
       ~DynamixelDevice.write_register
 
 
@@ -50,8 +48,6 @@ roboglia.dynamixel.DynamixelDevice
    .. automethod:: get_model_path
    .. automethod:: open
    .. automethod:: read_register
-   .. automethod:: register_by_address
-   .. automethod:: register_low_endian
    .. automethod:: write_register