diff --git a/contrib/README.md b/contrib/README.md
deleted file mode 100644
index 54a39a7..0000000
--- a/contrib/README.md
+++ /dev/null
@@ -1,212 +0,0 @@
-# Contrib
-
-Contrib libraries, or widget types, are extra snippets of code you can
-use. Some are for less common hardware, and other were contributed by
-Vicious users. The contrib directory also holds widget types that were
-obsoleted or rewritten. Contrib widgets will not be imported by init
-unless you explicitly enable it, or load them in your rc.lua.
-
-## Usage within Awesome
-
-To use contrib widgets uncomment the line that loads them in
-init.lua. Or you can load them in your rc.lua after you require
-Vicious:
-
-```lua
-local vicious = require("vicious")
-vicious.contrib = require("vicious.contrib")
-```
-
-## Widget types
-
-Most widget types consist of worker functions that take the `format`
-argument given to vicious.register as the first argument, `warg` as
-the second, and return a table of values to insert in the format
-string. But we have not insisted on this coding style in contrib. So
-widgets like PulseAudio have emerged that are different. These widgets
-could also depend on Lua libraries that are not distributed with the
-core Lua distribution. Ease of installation and use does not
-necessarily have to apply to contributed widgets.
-
-### vicious.contrib.ac
-
-Provide status about the power supply (AC).
-
-Supported platforms: GNU/Linux, requiring `sysfs`.
-
-* Argument: the AC device, i.e `"AC"` or `"ACAD"`. The device is linked under
-  `/sys/class/power_supply/` and should have a file called `online`.
-* Returns `{"On"}` if AC is connected, else `{"Off"}`. If AC doesn't exist,
-  returns `{"N/A"}`.
-
-### vicious.contrib.ati
-
-Provides various info about ATI GPU status.
-
-Supported platforms: GNU/Linux, requiring `sysfs`.
-
-* Argument: card ID, e.g. `"card0"` (and where possible,
-  uses `debugfs` to gather data on radeon power management)
-* Returns a table with string keys: `${method}`, `${dpm_state}`,
-  `${dpm_perf_level}`, `${profile}`, `${engine_clock mhz}`,
-  `${engine_clock khz}`, `${memory_clock mhz}`, `${memory_clock khz}`,
-  `${voltage v}`, `${voltage mv}`
-
-### vicious.contrib.batpmu
-
-### vicious.contrib.batproc
-
-### vicious.contrib.btc
-
-Provides current Bitcoin price in any currency by
-[code](https://en.wikipedia.org/wiki/ISO_4217).
-
-
-Platform independent, although requiring `curl` and either
-[lua-cjson](https://github.com/mpx/lua-cjson/) or
-[luajson](https://github.com/harningt/luajson/).
-
-* Argument: currency code, e.g. `"usd"`, `"rub"` and other. Default to `"usd"`.
-* Returns a table with string key `${price}`.
-
-### vicious.contrib.buildbot
-
-Provides last build status for configured buildbot builders
-(http://trac.buildbot.net/).
-
-Supported platforms: platform independent, though requiring Lua JSON parser
-[luajson](https://github.com/harningt/luajson/).
-
-Returns build status in the format:
-`[<builderName>.<currentBuildNumber>.<lastSuccessfulBuildNumber>]`.
-If `<currentBuildNumber>` is the same as `<lastSuccessfulBuildNumber>` only one
-number is displayed. `<buildNumber>` colors: red - failed, green - successful,
-yellow - in progress.
-
-### vicious.contrib.countfiles
-
-### vicious.contrib.cmus
-
-NOTE: This widget type has been promoted to `widgets`.
-
-Provides cmus player information using `cmus-remote`.
-
-Supported platforms: platform independent.
-
-* Argument: a table whose first field is the socket including host (or nil).
-* Returns a table with string keys: `${status}`, `${artist}`, `${title}`,
-  `${duration}`, `${file}`,  `${continue}`, `${shuffle}`, `${repeat}`.
-
-### vicious.contrib.dio
-
-Provides I/O statistics for requested storage devices.
-
-* Argument: the disk as an argument, i.e. `"sda"`, or a specific
-  partition, i.e. `"sda/sda2"`
-* Returns a table with string keys: `${total_s}`, `${total_kb}`, `${total_mb}`,
-  `${read_s}`, `${read_kb}`, `${read_mb}`, `${write_s}`, `${write_kb}`,
-  `${write_mb}` and `${sched}`
-
-### vicious.contrib.mpc
-
-### vicious.contrib.netcfg
-
-### vicious.contrib.net
-
-### vicious.contrib.openweather
-
-Provides weather information for a requested city
-
-* Argument: OpenWeatherMap city ID, e.g. `"1275339"`
-* Returns a table with string keys: `${city}`, `${wind deg}`, `${wind aim}`,
-  `${wind kmh}`, `${wind mps}`, `${sky}`, `${weather}`, `${temp c}`,
-  `${humid}` and `${press}`
-
-### vicious.contrib.nvinf
-
-Provides GPU utilization, core temperature, clock frequency information about
-Nvidia GPU from nvidia-settings
-
-Supported Platforms: platform independent
-
-* Argument (optional): card ID as an argument, e.g. `"1"`, default to ID 0
-* Returns an array containing:
-    * `$1`: Usage of GPU core
-    * `$2`: Usage of GPU memory
-    * `$3`: Usage of video engine
-    * `$4`: Usage of PCIe bandwidth
-    * `$5`: Uemperature of requested graphics device
-    * `$6`: Urequency of GPU core
-    * `$7`: Uemory transfer rate
-
-### vicious.contrib.nvsmi
-
-Provides (very basic) information about Nvidia GPU status from SMI
-
-Supported platforms: platform independent
-
-* Argument (optional): card ID as an argument, e.g. `"1"`, default to ID 0
-* Returns an array containing temperature of requested graphics device
-
-### vicious.contrib.ossvol
-
-### vicious.contrib.pop
-
-### vicious.contrib.pulse
-
-Provides volume levels of requested pulseaudio sinks and functions to
-manipulate them
-
-* Argument (optional): name of a sink as an optional argument. A number will
-  be interpret as an index, if no argument is given, it will take the
-  first-best. To get a list of available sinks run
-  `pacmd list-sinks | grep 'name:'`.
-* Returns an array whose only element is the volume level
-
-#### vicious.contrib.pulse.add(percent[, sink])
-
-* `percent` is the percentage to increment or decrement the volume from its
-  current value
-* Returns the exit status of `pacmd`
-
-#### vicious.contrib.pulse.toggle([sink])
-
-* Toggles mute state
-* Returns the exit status of `pacmd`
-
-### vicious.contrib.rss
-
-### vicious.contrib.sensors
-
-### vicious.contrib.wpa
-
-Provides information about the wifi status.
-
-Supported Platforms: platform independent, requiring `wpa_cli`.
-
-* Argument: the interface, e.g. `"wlan0"` or `"wlan1"`
-* Returns a table with string keys: `${ssid}`, `${qual}`, `${ip}`, `${bssid}`
-
-## Usage examples
-
-### Pulse Audio widget:
-
-```lua
-vol = wibox.widget.textbox()
-local sink = "alsa_output.pci-0000_00_1b.0.analog-stereo"
-vicious.register(vol, vicious.contrib.pulse, " $1%", 2, sink)
-vol:buttons(awful.util.table.join(
-    awful.button({}, 1, function () awful.util.spawn("pavucontrol") end),
-    awful.button({}, 4, function () vicious.contrib.pulse.add(5, sink) end),
-    awful.button({}, 5, function () vicious.contrib.pulse.add(-5, sink) end)))
-```
-
-### Buildbot widget
-
-```lua
-buildbotwidget = wibox.widget.textbox()
-vicious.register(
-    buildbotwidget, vicious.contrib.buildbot, "$1,", 3600,
-    {{builder="coverage", url="http://buildbot.buildbot.net"},
-     {builder="tarball-slave", url="http://buildbot.buildbot.net"}})
-```
diff --git a/docs/source/contrib.rst b/docs/source/contrib.rst
new file mode 100644
index 0000000..0826fdf
--- /dev/null
+++ b/docs/source/contrib.rst
@@ -0,0 +1,245 @@
+Contrib Widget Types
+====================
+
+Contrib libraries, or widget types, are extra snippets of code you can use.
+Some are for less common hardware, and other were contributed by Vicious users.
+The contrib directory also holds widget types that were obsoleted or rewritten.
+Contrib widgets will not be imported by init unless you explicitly enable it,
+or load them in your ``rc.lua``.
+
+Usage within Awesome
+--------------------
+
+To use contrib widgets uncomment the line that loads them in ``init.lua``.
+Or you can load them in your rc.lua after you require Vicious:
+
+.. code-block:: lua
+
+   local vicious = require"vicious"
+   vicious.contrib = require"vicious.contrib"
+
+Widget Types
+------------
+
+Most widget types consist of worker functions that take the ``format`` argument
+given to :lua:func:`vicious.register` as the first argument,
+``warg`` as the second, and return a table of values to insert in
+the format string.  But we have not insisted on this coding style in contrib.
+So widgets like PulseAudio have emerged that are different.  These widgets
+could also depend on Lua libraries that are not distributed with the
+core Lua distribution.  Ease of installation and use does not necessarily
+have to apply to contributed widgets.
+
+vicious.contrib.ac
+^^^^^^^^^^^^^^^^^^
+
+Provide status about the power supply (AC).
+
+Supported platforms: GNU/Linux, requiring ``sysfs``.
+
+* Argument: the AC device, i.e ``"AC"`` or ``"ACAD"``.  The device is linked
+  under ``/sys/class/power_supply/`` and should have a file called ``online``.
+* Returns ``{"On"}`` if AC is connected, else ``{"Off"}``.
+  If AC doesn't exist, returns ``{"N/A"}``.
+
+vicious.contrib.ati
+^^^^^^^^^^^^^^^^^^^
+
+Provides various info about ATI GPU status.
+
+Supported platforms: GNU/Linux, requiring ``sysfs``.
+
+* Argument: card ID, e.g. ``"card0"`` (and where possible,
+  uses ``debugfs`` to gather data on radeon power management)
+* Returns a table with string keys: ``${method}``, ``${dpm_state}``,
+  ``${dpm_perf_level}``, ``${profile}``, ``${engine_clock mhz}``,
+  ``${engine_clock khz}``, ``${memory_clock mhz}``, ``${memory_clock khz}``,
+  ``${voltage v}``, ``${voltage mv}``
+
+vicious.contrib.batpmu
+^^^^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.batproc
+^^^^^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.btc
+^^^^^^^^^^^^^^^^^^^
+
+Provides current Bitcoin price in any currency by
+[code](https://en.wikipedia.org/wiki/ISO_4217).
+
+
+Platform independent, although requiring ``curl`` and either
+[lua-cjson](https://github.com/mpx/lua-cjson/) or
+[luajson](https://github.com/harningt/luajson/).
+
+* Argument: currency code, e.g. ``"usd"``, ``"rub"`` and other.
+  Default to ``"usd"``.
+* Returns a table with string key ``${price}``.
+
+vicious.contrib.buildbot
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Provides last build status for configured buildbot builders
+(http://trac.buildbot.net/).
+
+Supported platforms: platform independent, though requiring Lua JSON parser
+[luajson](https://github.com/harningt/luajson/).
+
+Returns build status in the format:
+``[<builderName>.<currentBuildNumber>.<lastSuccessfulBuildNumber>]``.
+If ``<currentBuildNumber>`` is the same as ``<lastSuccessfulBuildNumber>``
+only one number is displayed.  ``<buildNumber>`` colors:
+red---failed, green---successful, yellow---in progress.
+
+vicious.contrib.countfiles
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.cmus
+^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   This widget type has been promoted to :ref:`widgets`.
+
+Provides cmus player information using ``cmus-remote``.
+
+Supported platforms: platform independent.
+
+* Argument: a table whose first field is the socket including host (or nil).
+* Returns a table with string keys: ``${status}``, ``${artist}``, ``${title}``,
+  ``${duration}``, ``${file}``,  ``${continue}``, ``${shuffle}``, ``${repeat}``.
+
+vicious.contrib.dio
+^^^^^^^^^^^^^^^^^^^
+
+Provides I/O statistics for requested storage devices.
+
+* Argument: the disk as an argument, i.e. ``"sda"``, or a specific
+  partition, i.e. ``"sda/sda2"``
+* Returns a table with string keys: ``${total_s}``, ``${total_kb}``,
+  ``${total_mb}``, ``${read_s}``, ``${read_kb}``, ``${read_mb}``,
+  ``${write_s}``, ``${write_kb}``, ``${write_mb}`` and ``${sched}``
+
+vicious.contrib.mpc
+^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.netcfg
+^^^^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.net
+^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.openweather
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Provides weather information for a requested city
+
+* Argument: OpenWeatherMap city ID, e.g. ``"1275339"``
+* Returns a table with string keys: ``${city}``, ``${wind deg}``,
+  ``${wind aim}``, ``${wind kmh}``, ``${wind mps}``, ``${sky}``,
+  ``${weather}``, ``${temp c}``, ``${humid}`` and ``${press}``
+
+vicious.contrib.nvinf
+^^^^^^^^^^^^^^^^^^^^^
+
+Provides GPU utilization, core temperature, clock frequency information about
+Nvidia GPU from nvidia-settings
+
+Supported Platforms: platform independent
+
+* Argument (optional): card ID as an argument, e.g. ``"1"``, default to ID 0
+* Returns an array containing:
+
+  * ``$1``: Usage of GPU core
+  * ``$2``: Usage of GPU memory
+  * ``$3``: Usage of video engine
+  * ``$4``: Usage of PCIe bandwidth
+  * ``$5``: Uemperature of requested graphics device
+  * ``$6``: Urequency of GPU core
+  * ``$7``: Uemory transfer rate
+
+vicious.contrib.nvsmi
+^^^^^^^^^^^^^^^^^^^^^
+
+Provides (very basic) information about Nvidia GPU status from SMI
+
+Supported platforms: platform independent
+
+* Argument (optional): card ID as an argument, e.g. ``"1"``, default to ID 0
+* Returns an array containing temperature of requested graphics device
+
+vicious.contrib.ossvol
+^^^^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.pop
+^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.pulse
+^^^^^^^^^^^^^^^^^^^^^
+
+Provides volume levels of requested pulseaudio sinks and functions to
+manipulate them
+
+* Argument (optional): name of a sink as an optional argument. A number will
+  be interpret as an index, if no argument is given, it will take the
+  first-best. To get a list of available sinks run
+  ``pacmd list-sinks | grep 'name:'``.
+* Returns an array whose only element is the volume level
+
+vicious.contrib.pulse.add(percent[, sink])
+""""""""""""""""""""""""""""""""""""""""""
+
+* ``percent`` is the percentage to increment or decrement the volume
+  from its current value
+* Returns the exit status of ``pacmd``
+
+vicious.contrib.pulse.toggle([sink])
+""""""""""""""""""""""""""""""""""""
+
+* Toggles mute state
+* Returns the exit status of ``pacmd``
+
+vicious.contrib.rss
+^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.sensors
+^^^^^^^^^^^^^^^^^^^^^^^
+
+vicious.contrib.wpa
+^^^^^^^^^^^^^^^^^^^
+
+Provides information about the wifi status.
+
+Supported Platforms: platform independent, requiring ``wpa_cli``.
+
+* Argument: the interface, e.g. ``"wlan0"`` or ``"wlan1"``
+* Returns a table with string keys:
+  ``${ssid}``, ``${qual}``, ``${ip}``, ``${bssid}``
+
+Usage Examples
+--------------
+
+PulseAudio Widget
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: lua
+
+   vol = wibox.widget.textbox()
+   local sink = "alsa_output.pci-0000_00_1b.0.analog-stereo"
+   vicious.register(vol, vicious.contrib.pulse, " $1%", 2, sink)
+   vol:buttons(awful.util.table.join(
+       awful.button({}, 1, function () awful.util.spawn("pavucontrol") end),
+       awful.button({}, 4, function () vicious.contrib.pulse.add(5, sink) end),
+       awful.button({}, 5, function () vicious.contrib.pulse.add(-5, sink) end)))
+
+Buildbot Widget
+^^^^^^^^^^^^^^^
+
+.. code-block:: lua
+
+   buildbotwidget = wibox.widget.textbox()
+   vicious.register(
+       buildbotwidget, vicious.contrib.buildbot, "$1,", 3600,
+       { { builder="coverage", url="http://buildbot.buildbot.net" },
+         { builder="tarball-slave", url="http://buildbot.buildbot.net" } })
diff --git a/docs/source/index.rst b/docs/source/index.rst
index e66e2d9..67324e8 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -22,6 +22,7 @@ Table of Contents
    usage-awesome
    examples
    widgets
+   contrib
    custom
    format
    caching