From 071cc61a582d3877c33b4ace5ee7e3e5abf51bf1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nguy=E1=BB=85n=20Gia=20Phong?= Date: Sun, 13 Sep 2020 17:53:27 +0700 Subject: [PATCH] [docs] Include contrib widget types --- contrib/README.md | 212 ---------------------------------- docs/source/contrib.rst | 245 ++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 3 files changed, 246 insertions(+), 212 deletions(-) delete mode 100644 contrib/README.md create mode 100644 docs/source/contrib.rst 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: -`[..]`. -If `` is the same as `` only one -number is displayed. `` 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: +``[..]``. +If ```` is the same as ```` +only one number is displayed. ```` 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