Major documentation upgrade

CHANGELOG.rst

@@ -2,34 +2,32 @@ Changelog
 =========
 
 v0.9.0 (release candidate)
+--------------------------
 
-  No major new features, API cleanup to ensure that connections are
-  properly closed. Functions that return binary data return ``bytes``.
+No major new features, API cleanup to ensure that connections are
+properly closed. Functions that return binary data return ``bytes``.
 
-  * implement dummy context management protocol for ``_Proxy``
-    for consitency with _PersistentProxy
-  * OwnetProxy class deprecated
-  * create a diagnostics directory ``./diags``
-  * move test suite from ``./test`` to ``./tests``
-  * ``pyownet.protocol._OwnetConnection.req()`` returns ``bytes`` and not
-    ``bytearray``
+* implement dummy context management protocol for ``_Proxy``
+  for consitency with _PersistentProxy
+* ``OwnetProxy`` class deprecated
+* create a diagnostics directory ``./diags``
+* move test suite from ``./test`` to ``./tests``
+* ``pyownet.protocol._OwnetConnection.req()`` returns ``bytes`` and not
+  ``bytearray``
 
-    This is due to a simplification in
-    ``pyownet.protocol._OwnetConnection._read_socket()`` method.
-  * better connection logic in ``pyownet.protocol.proxy()`` factory:
-    first connect or raise ``protocol.ConnError``,
-    then test owserver protocol or raise ``protocol.ProtocolError``
-  * use relative imports in ``pyownet.protocol``
-  * ``./test`` and ``./examples`` minor code refactor
-  * ``.gitignore`` cleanup (use only project specific ignores)
-  * add ``__del__`` in ``_PersistentProxy`` to ensure connection is closed
-  * use ``with _OwnetConnection`` inside ``_Proxy`` to shutdown sockets
-  * implement context management protocol for ``_OwnetConnection`` to
-    guarantee that connection is shutdown on exit
-  * py26 testing via ``unittest2``
-  * transform ``./test`` directory in package, so that common code
-    (used for reading configuration files) can be shared more easily
-  * move ``./pyownet`` to ``./src/pyownet``
-
-v0.8.2 2015-08-26
-  base for changelog
+  This is due to a simplification in
+  ``pyownet.protocol._OwnetConnection._read_socket()`` method.
+* better connection logic in ``pyownet.protocol.proxy()`` factory:
+  first connect or raise ``protocol.ConnError``,
+  then test owserver protocol or raise ``protocol.ProtocolError``
+* use relative imports in ``pyownet.protocol``
+* ``./test`` and ``./examples`` minor code refactor
+* ``.gitignore`` cleanup (use only project specific ignores)
+* add ``__del__`` in ``_PersistentProxy`` to ensure connection is closed
+* use ``with _OwnetConnection`` inside ``_Proxy`` to shutdown sockets
+* implement context management protocol for ``_OwnetConnection`` to
+  guarantee that connection is shutdown on exit
+* py26 testing via ``unittest2``
+* transform ``./test`` directory in package, so that common code
+  (used for reading configuration files) can be shared more easily
+* move ``./pyownet`` to ``./src/pyownet``

README.rst

@@ -1,38 +1,52 @@
-pyownet, a pure python owserver client library
-==============================================
+pyownet: Python OWFS client library (owserver protocol)
+=======================================================
 
-|docs|
-
-.. |docs| image:: https://readthedocs.org/projects/pyownet/badge/?version=latest&style=flat
+.. image:: https://readthedocs.org/projects/pyownet/badge/?version=latest&style=flat
    :target: http://pyownet.readthedocs.org/en/latest/
    :alt: Package Documentation
 
-pyownet is a pure python package that allows client access to an `owserver`_
-via the `owserver network protocol`_, in short *ownet*.
-
-owserver is part of the `OWFS 1-Wire File System`_:
-
-    OWFS is an easy way to use the powerful 1-wire system of
-    Dallas/Maxim.
-
-    OWFS is a simple and flexible program to monitor and control the
-    physical environment. You can write scripts to read temperature,
-    flash lights, write to an LCD, log and graph, ...
+.. image:: https://img.shields.io/pypi/v/pyownet.svg
+   :target: https://pypi.python.org/pypi/pyownet
+   :alt: Python Package Index version
 
-The ``pyownet.protocol`` module is a low-level implementation of the
-owserver client protocol. Interaction with an owserver takes place via a proxy
-object whose methods correspond to owserver messages:
+Pyownet is a pure python package that allows network client access to
+the `OWFS 1-Wire File System`_ via an `owserver`_ and the `owserver
+network protocol`_, in short *ownet*.
 
-::
+The ``pyownet.protocol`` module is an implementation of the owserver
+client protocol that exposes owserver messages as methods of a proxy
+object::
 
     >>> owproxy = pyownet.protocol.proxy(host="owserver.example.com", port=4304)
     >>> owproxy.dir()
     ['/10.67C6697351FF/', '/05.4AEC29CDBAAB/']
     >>> owproxy.read('/10.67C6697351FF/temperature')
     '     91.6195'
 
-Python 3 is fully supported via ``2to3`` and ``use_2to3 = True`` in
-``setup.py``.
+Installation
+------------
+
+To install pyownet::
+
+    $ pip install pyownet
+
+
+Python version support
+----------------------
+
+The code base is written in Python 2, but Python 3 is fully supported,
+and is the main developing language. Running the ``2to3`` tool will
+generate valid and, whenever possible, idiomatic Python 3 code.
+
+Explicitly supported versions are Python 2.6, 2.7, 3.2 through 3.5.
+
+
+Documentation
+-------------
+
+Full package documentation is available at
+http://pyownet.readthedocs.org/en/latest/
+
 
 .. _owserver: http://owfs.org/index.php?page=owserver_protocol
 .. _owserver network protocol: http://owfs.org/index.php?page=owserver-protocol

docs/installation.rst

@@ -1,10 +1,22 @@
 Installation
 ============
 
-pyownet is `hosted`_ on GitHub and is `registered`_ on PyPI.
+Source code
+-----------
 
-.. _hosted: https://github.com/miccoli/pyownet
-.. _registered: https://pypi.python.org/pypi/pyownet
+Source code for pyownet is hosted on GitHub:
+https://github.com/miccoli/pyownet . The project is registered on
+PyPI: https://pypi.python.org/pypi/pyownet .
+
+Python version support
+^^^^^^^^^^^^^^^^^^^^^^
+
+The code base is written in Python 2, but Python 3 is fully supported,
+and is the main developing language. Running the ``2to3`` tool will
+generate valid and, whenever possible, idiomatic Python 3 code. The
+present documentation refers to the Python 3 version of the package.
+
+Explicitly supported versions are Python 2.6, 2.7, 3.2 through 3.5.
 
 Install from PyPI
 -----------------
@@ -14,9 +26,11 @@ The preferred installation method is from `PyPI`_ via `pip`_: ::
   pip install pyownet
 
 This will install the :py:mod:`pyownet` package in the default
-location. If you are also interestend in usage examples and tests you
-can download the source package from the PyPI `downloads`_, unpack it,
-and install::
+location.
+
+If you are also interested in usage examples and tests you can
+download the source package from the PyPI `downloads`_, unpack it, and
+install::
 
   python setup.py install
 

docs/intro.rst

@@ -34,7 +34,7 @@ allows to access a 1-Wire bus via a supported master device. OWFS
 comprises many different modules which offer different access
 protocols to 1-Wire data: ``owhttpd`` (http), ``owftpd`` (ftp) and
 ``owfs`` (filesystem interface via FUSE). Since only a single program
-can access the 1-Wire bus at one time, there is also backend
+can access the 1-Wire bus at one time, there is also a back end
 component, ``owserver``, that arbitrates access to the bus from
 multiple client processes. Client processes can query an ``owserver``
 (the program) via network sockets speaking the 'owserver'