From d35eeb2ed3ee7e88e39f4fdab94271e3dc157305 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nguy=E1=BB=85n=20Gia=20Phong?= Date: Sun, 13 Sep 2020 16:52:40 +0700 Subject: [PATCH] [docs] Move examples from README --- README.md | 92 ------------------------------------- docs/source/examples.rst | 97 ++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 7 +-- 3 files changed, 101 insertions(+), 95 deletions(-) create mode 100644 docs/source/examples.rst diff --git a/README.md b/README.md index bc43436..c788eab 100644 --- a/README.md +++ b/README.md @@ -12,96 +12,6 @@ timers, suspend widgets and so on. Vicious doesn't depend on any third party Lua libraries, but may depend on additional system utilities (see widget description). - -## Usage examples - -Start with a simple widget, like `date`. Then build your setup from -there, one widget at a time. Also remember that besides creating and -registering widgets you have to add them to a `wibox` (statusbar) in -order to actually display them. - -### Date widget - -Update every 2 seconds (the default interval), use standard date sequences as -the format string: - -```lua -datewidget = wibox.widget.textbox() -vicious.register(datewidget, vicious.widgets.date, "%b %d, %R") -``` - -### Memory widget - -Update every 13 seconds, append `MiB` to 2nd and 3rd returned values and -enables caching. - -```lua -memwidget = wibox.widget.textbox() -vicious.cache(vicious.widgets.mem) -vicious.register(memwidget, vicious.widgets.mem, "$1 ($2MiB/$3MiB)", 13) -``` - -### HDD temperature widget - -Update every 19 seconds, request the temperature level of the /dev/sda and -append *°C* to the returned value. Since the listening port is not provided, -default one is used. - -```lua -hddtempwidget = wibox.widget.textbox() -vicious.register(hddtempwidget, vicious.widgets.hddtemp, "${/dev/sda} °C", 19) -``` - -### Mbox widget - -Updated every 5 seconds, provide full path to the mbox as argument: - -```lua -mboxwidget = wibox.widget.textbox() -vicious.register(mboxwidget, vicious.widgets.mbox, "$1", 5, - "/home/user/mail/Inbox") -``` - -### Battery widget - -Update every 61 seconds, request the current battery charge level and displays -a progressbar, provides `"BAT0"` as battery ID: - -```lua -batwidget = wibox.widget.progressbar() - --- Create wibox with batwidget -batbox = wibox.layout.margin( - wibox.widget{{max_value = 1, widget = batwidget, - border_width = 0.5, border_color = "#000000", - color = {type = "linear", - from = {0, 0}, - to = {0, 30}, - stops = {{0, "#AECF96"}, {1, "#FF5656"}}}}, - forced_height = 10, forced_width = 8, - direction = 'east', color = beautiful.fg_widget, - layout = wibox.container.rotate}, - 1, 1, 3, 3) - --- Register battery widget -vicious.register(batwidget, vicious.widgets.bat, "$2", 61, "BAT0") -``` - -### CPU usage widget - -Update every 3 seconds, feed the graph with total usage percentage of all -CPUs/cores: - -```lua -cpuwidget = awful.widget.graph() -cpuwidget:set_width(50) -cpuwidget:set_background_color"#494B4F" -cpuwidget:set_color{type = "linear", from = {0, 0}, to = {50, 0}, - stops = {{0, "#FF5656"}, {0.5, "#88A175"}, {1, "#AECF96"}}} -vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3) -``` - - ## Contributing For details, see CONTRIBUTING.md. Vicious is licensed under GNU GPLv2+, @@ -109,7 +19,6 @@ which require all code within the package to be released under a compatible license. All contributors retain their copyright to their code, so please make sure you add your name to the header of every file you touch. - ## Copying Vicious is free software: you can redistribute it and/or modify @@ -119,5 +28,4 @@ License, or (at your option) any later version. Please refer to our documentation for the full [list of authors]. - [list of authors]: https://vicious.rtfd.io/copying.html diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 0000000..f57d7ed --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,97 @@ +Usage Examples +============== + +Start with a simple widget, like ``date``, then build your setup from there, +one widget at a time. Also remember that besides creating and registering +widgets you have to add them to a ``wibox`` (statusbar) in order to +actually display them. + +Date Widget +----------- + +Update every 2 seconds (the default interval), +use standard date sequences as the format string: + +.. code-block:: lua + + datewidget = wibox.widget.textbox() + vicious.register(datewidget, vicious.widgets.date, "%b %d, %R") + +Memory Widget +------------- + +Update every 13 seconds, append ``MiB`` to 2nd and 3rd returned values +and enables caching. + +.. code-block:: lua + + memwidget = wibox.widget.textbox() + vicious.cache(vicious.widgets.mem) + vicious.register(memwidget, vicious.widgets.mem, "$1 ($2MiB/$3MiB)", 13) + +HDD Temperature Widget +---------------------- + +Update every 19 seconds, request the temperature level of ``/dev/sda`` and +append *°C* to the returned value. Since the listening port is not provided, +default one is used. + +.. code-block:: lua + + hddtempwidget = wibox.widget.textbox() + vicious.register(hddtempwidget, vicious.widgets.hddtemp, "${/dev/sda} °C", 19) + +Mbox Widget +----------- + +Updated every 5 seconds, provide full path to the mbox as argument: + +.. code-block:: lua + + mboxwidget = wibox.widget.textbox() + vicious.register(mboxwidget, vicious.widgets.mbox, "$1", 5, + "/home/user/mail/Inbox") + +Battery Widget +-------------- + +Update every 61 seconds, request the current battery charge level +and displays a progressbar, provides ``BAT0`` as battery ID: + +.. code-block:: lua + + batwidget = wibox.widget.progressbar() + + -- Create wibox with batwidget + batbox = wibox.layout.margin( + wibox.widget{ { max_value = 1, widget = batwidget, + border_width = 0.5, border_color = "#000000", + color = { type = "linear", + from = { 0, 0 }, + to = { 0, 30 }, + stops = { { 0, "#AECF96" }, + { 1, "#FF5656" } } } }, + forced_height = 10, forced_width = 8, + direction = 'east', color = beautiful.fg_widget, + layout = wibox.container.rotate }, + 1, 1, 3, 3) + + -- Register battery widget + vicious.register(batwidget, vicious.widgets.bat, "$2", 61, "BAT0") + +CPU Usage Widget +---------------- + +Update every 3 seconds, feed the graph with total usage percentage +of all CPUs/cores: + +.. code-block:: lua + + cpuwidget = awful.widget.graph() + cpuwidget:set_width(50) + cpuwidget:set_background_color"#494B4F" + cpuwidget:set_color{ type = "linear", from = { 0, 0 }, to = { 50, 0 }, + stops = { { 0, "#FF5656" }, + { 0.5, "#88A175" }, + { 1, "#AECF96" } } } + vicious.register(cpuwidget, vicious.widgets.cpu, "$1", 3) diff --git a/docs/source/index.rst b/docs/source/index.rst index 7e115e7..796ee35 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,5 +1,5 @@ -Welcome to Vicious's documentation! -=================================== +Welcome to Vicious' documentation! +================================== Vicious is a modular widget library for window managers, but mostly catering to users of the `awesome window manager`_. It was derived from the old @@ -16,10 +16,11 @@ Table of Contents ----------------- .. toctree:: - :titlesonly: + :maxdepth: 2 usage-lua usage-awesome + examples widgets custom format