redesign documentation and cleanup docstrings

Several elements from the new documentation have been inspired or
outright stolen from Plumbum's excellent landing page.

.gitignore

@@ -14,6 +14,7 @@ TAGS
 evdev/*.so
 evdev/ecodes.c
 doc/_build
+.#*
 __pycache__
 
 evdev/_ecodes.py

doc/Makefile

@@ -41,10 +41,12 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 
+
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@sed -i $(BUILDDIR)/html/index.html -e 's,<span>Synopsis</span>,<span>Python Bindings</span>,'
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -152,6 +154,13 @@ doctest:
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
 
+
+# .PHONY: news.rst
+# news.rst: changelog.rst
+# 	cat $< | grep -FB1 '^^^^^^^^^' \
+# 	| sed -e '/^\^/d;/--/d' -e 's,\(.*\)(\(.*\)),* **\2**: Version \1released.\n,' \
+# 	> $@
+
 $(BUILDDIR)/html/evdev-doc.zip: html
 	cd $(BUILDDIR)/html/ &&  zip -x \*.zip -r evdev-doc.zip .
 	@echo `readlink -f $@`

doc/apidoc.rst

@@ -1,5 +1,5 @@
-API documentation
------------------
+API Reference
+-------------
 
 ``events``
 ============
@@ -23,8 +23,8 @@ API documentation
 ``uinput``
 ============
 
-.. autoclass:: evdev.uinput.UInput
-   :members:
+.. automodule:: evdev.uinput
+   :members: UInput
    :special-members:
    :exclude-members: __dict__, __str__, __module__, __del__, __slots__, __repr__
    :member-order: bysource

doc/changelog.rst

@@ -1,6 +1,13 @@
 Changelog
 =========
 
+HEAD
+^^^^^^^^^^^^^^^^^^^^
+
+- Rework documentation and docstrings once more.
+
+- Fix install on Python 3.4 (works around issue21121_).
+
 0.4.5 (Jul 06, 2014)
 ^^^^^^^^^^^^^^^^^^^^
 
@@ -162,3 +169,5 @@ Changelog
 .. _`@accek`: https://github.com/accek
 .. _`@kived`: https://github.com/kived
 .. _`@spasche`: https://github.com/spasche
+
+.. _issue21121: http://bugs.python.org/issue21121

doc/conf.py

@@ -33,6 +33,8 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx']
 
+autodoc_member_order = 'bysource'
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -47,7 +49,7 @@
 
 # General information about the project.
 project = u'python-evdev'
-copyright = u'2012-2013, Georgi Valkov'
+copyright = u'2012-2014, Georgi Valkov'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -99,30 +101,30 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-if not on_rtd:
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-else:
-    html_theme = 'default'
+# if not on_rtd:
+#     import sphinx_rtd_theme
+#     html_theme = 'sphinx_rtd_theme'
+#     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# else:
+html_theme = 'haiku'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+# html_theme_options = {"full_logo" : True}
 
 # Add any paths that contain custom themes here, relative to this directory.
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-#html_title = None
+html_title = 'Python-evdev'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+html_short_title = 'evdev'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = '_static/evdev-logo-small.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

doc/index.rst

@@ -1,5 +1,37 @@
-*evdev* documentation
----------------------
+.. raw:: html
+
+    <div style="float:right;
+         margin:1em;
+         padding: 0.5em 1em 0em 1em;
+         background-color: #efefef;
+         border-width: thin;
+         border-style: dotted;
+         border-color: #0C3762;
+         ">
+    <strong>Links</strong><br/>
+    <ul>
+    <li><a href="#news"  title="Jump to News">News</a></li>
+    <li><a href="search.html"  title="Jump to Search">Search</a></li>
+    <li><a href="#quick-start" title="Jump to quick start">Quick Start</a></li>
+    <li><a href="apidoc.html"  title="Jump to API reference">API Reference</a></li>
+    <li><a href="https://github.com/gvalkov/python-evdev"  title="Jump to Github">Github</a></li>
+    </ul>
+    <!--
+    <hr/>
+    <a href="https://github.com/gvalkov/python-evdev">
+    <img style="
+         display: block;
+         margin-left: auto;
+         margin-right: auto;
+         opacity: 0.9;
+         width: 50px;"
+    src="_static/github-logo.png" title="Github Repo"/>
+    </a>
+    -->
+    </div>
+
+Synopsis
+--------
 
 This package provides bindings to the generic input event interface in
 Linux. The *evdev* interface serves the purpose of passing events
@@ -11,61 +43,173 @@ subsystem. *Uinput* allows userspace programs to create and handle
 input devices that can inject events directly into the input
 subsystem.
 
-Please refer to the :doc:`tutorial <tutorial>` and the :doc:`apidoc
-<apidoc>` for usage information.
+In other words, *python-evdev* allows you to read and write input
+events on Linux. An event can be a key or button press, a mouse
+movement or a tap on a touchscreen.
 
-Contents
-========
+Quick Start
+-----------
 
-.. toctree::
-   :maxdepth: 1
+**Installing:**
 
-   tutorial
-   install
-   apidoc
-   changelog
+The following GNU/Linux distributions have *python-evdev* in their repositories:
 
+.. raw:: html
 
-Similar Projects
-================
+    <div style="margin:1em;">
+    <a href="https://aur.archlinux.org/packages/python-evdev/"><img height="40px" src="_static/pacifica-icon-set/distributor-logo-archlinux.png"></a>
+    <a href="http://packages.ubuntu.com/saucy/python-evdev">   <img height="40px" src="_static/pacifica-icon-set/distributor-logo-ubuntu.png"></a>
+    <!--
+    <a href=""><img height="40px" src="_static/pacifica-icon-set/distributor-logo-raspbian.png"></a>
+    <a href=""><img height="40px" src="_static/pacifica-icon-set/distributor-logo-fedora.png"></a>
+    <a href=""><img height="40px" src="_static/pacifica-icon-set/distributor-logo-debian.png"></a>
+    <a href=""><img height="40px" src="_static/pacifica-icon-set/distributor-logo-linux-mint.png"></a>
+    <a href=""><img height="40px" src="_static/pacifica-icon-set/distributor-logo-opensuse.png"></a>
+    --!>
+    </div>
 
-* `python-uinput`_
-* `ruby-evdev`_
-* `evdev`_ (ctypes)
+The latest stable version of *python-evdev* can be installed from
+pypi_, provided that you have gcc/clang, pip_ and the Python and Linux
+development headers installed on your system. Installing them is
+distribution specific and usually falls in one of these categories:
 
+On a Debian compatible OS:
 
-License
-=======
+.. code-block:: bash
+
+    $ apt-get install python-dev python-pip gcc
+    $ apt-get install linux-headers-$(uname -r)
+
+On a Redhat compatible OS:
+
+.. code-block:: bash
+
+    $ yum install python-devel python-pip gcc
+    $ yum install kernel-headers-$(uname -r)
+
+On Arch Linux and derivatives:
+
+.. code-block:: bash
+
+    $ pacman -S core/linux-headers python-pip gcc
+
+Installing *python-evdev* with pip_:
+
+.. code-block:: bash
+
+    $ sudo pip install evdev
+
+**Listing accessible event devices:**
+
+::
+
+    >>> from evdev import InputDevice, list_devices
+
+    >>> devices = [InputDevice(fn) for fn in list_devices()]
+    >>> for dev in devices:
+    ...    print(dev.fn, dev.name, dev.phys)
+    /dev/input/event1    Dell Dell USB Keyboard   usb-0000:00:12.1-2/input0
+    /dev/input/event0    Dell USB Optical Mouse   usb-0000:00:12.0-2/input0
+
+
+**Reading events from a device:**
+
+::
+
+    >>> from evdev import InputDevice, categorize, ecodes
+
+    >>> dev = InputDevice('/dev/input/event1')
+    >>> print(dev)
+    device /dev/input/event1, name "Dell Dell USB Keyboard", phys "usb-0000:00:12.1-2/input0"
+
+    >>> for event in dev.read_loop():
+    ...     if event.type == ecodes.EV_KEY:
+    ...         print(categorize(event))
+    ... # pressing 'a' and holding 'space'
+    key event at 1337016188.396030, 30 (KEY_A), down
+    key event at 1337016188.492033, 30 (KEY_A), up
+    key event at 1337016189.772129, 57 (KEY_SPACE), down
+    key event at 1337016190.275396, 57 (KEY_SPACE), hold
+    key event at 1337016190.284160, 57 (KEY_SPACE), up
+
+**Accessing evdev constants:**
 
-Package :mod:`evdev` is released under the terms of the `Revised BSD License`_.
+::
 
+    >>> from evdev import ecodes
 
-Todo
-====
+    >>> ecodes.KEY_A, ecodes.ecodes['KEY_A']
+    ... (30, 30)
+    >>> ecodes.KEY[30]
+    ... 'KEY_A'
+    >>> ecodes.bytype[ecodes.EV_KEY][30]
+    ... 'KEY_A'
+    >>> ecodes.KEY[152]  # a single value may correspond to multiple codes
+    ... ['KEY_COFFEE', 'KEY_SCREENLOCK']
 
-* Use libudev to find the uinput device node as well as the other input
-  devices. Their locations are currently assumed to be ``/dev/uinput`` and
-  ``/dev/input/*``.
+**Further information:**
 
-* More tests.
+- Read the full :doc:`tutorial <tutorial>`.
 
-* Better uinput support (setting device capabilities as in `python-uinput`_)
+- See the example_ programs.
 
-* Expose more input subsystem functionality (``EVIOCSKEYCODE``, ``EVIOCGREP`` etc)
+- Refer to the API :doc:`documentation <apidoc>`:
 
-* Figure out if using ``linux/input.h`` and other kernel headers in your
-  userspace program binds it to the GPL2.
+  * :mod:`device <evdev.device>`
 
+    - :class:`AbsInfo <evdev.device.AbsInfo>`
 
-Indices and Tables
-==================
+    - :class:`KbdInfo <evdev.device.KbdInfo>`
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    - :class:`InputDevice <evdev.device.InputDevice>`
 
+  * :mod:`events <evdev.events>`
+
+    - :class:`InputEvent <evdev.events.InputEvent>`
+
+    - :class:`KeyEvent <evdev.events.KeyEvent>`
+
+    - :class:`RelEvent <evdev.events.RelEvent>`
+
+    - :class:`AbsEvent <evdev.events.AbsEvent>`
+
+    - :class:`SynEvent <evdev.events.SynEvent>`
+
+  * :mod:`util <evdev.util>`
+
+    - :class:`list_devices() <evdev.util.list_devices>`
+
+    - :class:`is_device() <evdev.util.is_device>`
+
+    - :class:`categorize() <evdev.util.categorize>`
+
+    - :class:`categorize() <evdev.util.categorize>`
+
+  * :mod:`uinput <evdev.uinput>`
+
+    - :class:`UInput <evdev.uinput.UInput>`
+
+  * :mod:`ecodes <evdev.ecodes>`
+
+
+News
+----
+.. include:: news.rst
+
+See :doc:`changelog <changelog>` for a full list of changes.
+
+
+License
+-------
+
+The :mod:`evdev` package is released under the terms of the `Revised BSD License`_.
 
 .. _`Revised BSD License`: https://raw.github.com/gvalkov/python-evdev/master/LICENSE
 .. _python-uinput:     https://github.com/tuomasjjrasanen/python-uinput
 .. _ruby-evdev:        http://technofetish.net/repos/buffaloplay/ruby_evdev/doc/
 .. _evdev:             http://svn.navi.cx/misc/trunk/python/evdev/
+
+.. _pypi:              http://pypi.python.org/pypi/evdev
+.. _github:            https://github.com/gvalkov/python-evdev
+.. _pip:               http://pip.readthedocs.org/en/latest/installing.html
+.. _example:           https://github.com/gvalkov/python-evdev/tree/master/bin