Obvious

The Obvious Repository is a set of widgets for your awesome desktop that provide helpful information. It's an independent project that has the community support.

Getting the Obvious Repo
First go to your awesome dir in XDG_CONFIG_HOME (which should be ~/.config).

$ cd $XDG_CONFIG_HOME/awesome

Then clone the repository in this directory:

$ git clone git@github.com:hoelzro/obvious.git

You can check the widgets available by going into the new obvious directory and looking at the folders.

Obvious version
Obvious master uses bleeding edge updates from awesome master. You should checkout the obvious version tagged with your current awesome version.

Adding widgets to your desktop
Now that you've got the repo it's time to add the widgets you want. Go into the directory of the widget you're interested and read the readme provided there. It will explain the specifics of implementing this particular widget. Generally, this is pretty easy, and generally follows the format of:
 * "require" the correct module at the top of your rc.lua.
 * Configure some settings for the module.
 * Add the widget to your wibox's widget list.
 * Add bindings to it.

A lot of the time, the bindings/configurations aren't necessary, so it's just two lines worth of changes. Example (the volume control):
 * require("obvious.volume_alsa") -- Load the module
 * obvious.volume_alsa.setchannel("Master") -- Configure the module
 * obvious.volume_alsa, -- Add this to your widgets list
 * awful.key({ modkey }, "m", obvious.volume_alsa.mute), -- Add a bind for the widget

Writing new modules
Feel free to write an obvious module if you have a great idea and would like to implement it. Submit them to awesome-devel@naquadah.org. You should sign up for this mailing list. Check the API Documentation for info about functions you may use. Also, check out the "CONTRIBUTING" file in the obvious source code for full description.