From 49c1465b655ed032fc1b4468b109e867da5ef3ca Mon Sep 17 00:00:00 2001 From: tobi-wan-kenobi Date: Mon, 4 May 2020 20:02:48 +0200 Subject: [PATCH] [docs] significant revamp - add sphinx support make it possible to compile documentation via sphinx - main change is to use RST instead of MarkDown for most files. --- CONTRIBUTING.md | 2 +- README.md | 20 +- doc/FAQ.md | 25 - doc/FEATURES.md | 89 --- doc/LIST-OF-MODULES.md | 89 --- doc/LIST-OF-THEMES.md | 71 -- doc/development/WRITING-A-MODULE.md | 130 ---- doc/development/WRITING-A-THEME.md | 111 ---- docs/FAQ.rst | 38 ++ docs/Makefile | 20 + docs/conf.py | 52 ++ docs/development/index.rst | 16 + docs/development/module.rst | 160 +++++ docs/development/theme.rst | 132 ++++ docs/features.rst | 131 ++++ docs/index.rst | 25 + docs/introduction.rst | 131 ++++ docs/make.bat | 35 + docs/modules.rst | 974 ++++++++++++++++++++++++++++ {doc => docs}/other/NOTES.md | 0 docs/themes.rst | 134 ++++ 21 files changed, 1859 insertions(+), 526 deletions(-) delete mode 100644 doc/FAQ.md delete mode 100644 doc/FEATURES.md delete mode 100644 doc/LIST-OF-MODULES.md delete mode 100644 doc/LIST-OF-THEMES.md delete mode 100644 doc/development/WRITING-A-MODULE.md delete mode 100644 doc/development/WRITING-A-THEME.md create mode 100644 docs/FAQ.rst create mode 100644 docs/Makefile create mode 100644 docs/conf.py create mode 100644 docs/development/index.rst create mode 100644 docs/development/module.rst create mode 100644 docs/development/theme.rst create mode 100644 docs/features.rst create mode 100644 docs/index.rst create mode 100644 docs/introduction.rst create mode 100644 docs/make.bat create mode 100644 docs/modules.rst rename {doc => docs}/other/NOTES.md (100%) create mode 100644 docs/themes.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 60031a4..099a62e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,7 +11,7 @@ If you want to file a bug, simply open an issue and describe your problem. Thing But even if you can't provide those, any indicator that something is not working as it should is much appreciated! ### Adding a new module or theme -If you want to add a new module, please have a look at [how to write a new module](doc/HOWTO_MODULE.md) and [how to write a new theme](doc/HOWTO_THEME.md). Then simply create a Pull Request and I will review the changes as soon as possible. +If you want to add a new module, please have a look at [how to write a new module](docs/development/module.rst) and [how to write a new theme](docs/development/theme.rst). Then simply create a Pull Request and I will review the changes as soon as possible. If you want to do me a *big* favour, check the Travis status for any failing unit tests. Oh - and if you happen to add unit tests, that's also something I am very grateful for! Thanks for reading until here! :) diff --git a/README.md b/README.md index a80399a..ceecd6d 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ **Many, many thanks to all contributors! I am still amazed by and deeply grateful for how many PRs this project gets.** -![List of modules](doc/LIST-OF-MODULES.md) +![List of modules](docs/modules.rst) ![Solarized Powerline](screenshots/themes/powerline-solarized.png) @@ -15,8 +15,8 @@ bumblebee-status is a modular, theme-able status line generator for the [i3 wind Focus is on: * ease of use, sane defaults (no mandatory configuration file) -* [custom themes](doc/development/WRITING-A-THEME.md) -* [custom modules](doc/development/WRITING-A-MODULE.md) +* [custom themes](docs/development/theme.rst) +* [custom modules](docs/development/module.rst) I hope you like it and I appreciate any kind of feedback: bug reports, feature requests, etc. :) @@ -37,15 +37,15 @@ bar { ``` # Documentation -See [the docs](doc/) for detailed documentation. +See [the docs](docs/) for detailed documentation. -See [FAQ](doc/FAQ.md) for. well, FAQs. +See [FAQ](docs/FAQ.rst) for. well, FAQs. Other resources: -* A list of [available modules](doc/LIST-OF-MODULES.md) -* [How to write a module](doc/development/WRITING-A-MODULE.md) -* [How to write a theme](doc/development/WRITING-A-THEME.md) +* A list of [available modules](docs/modules.rst) +* [How to write a module](docs/development/module.rst) +* [How to write a theme](docs/development/theme.rst) # Installation ``` @@ -63,7 +63,7 @@ pip install --user bumblebee-status ``` # Dependencies -[Available modules](doc/LIST-OF-MODULES.md) lists the dependencies (Python modules and external executables) +[Available modules](docs/modules.rst) lists the dependencies (Python modules and external executables) for each module. If you are not using a module, you don't need the dependencies. # Usage @@ -118,4 +118,4 @@ Restart i3wm and - that's it! # Examples -![List of themes](./doc/LIST-OF-THEMES.md) +![List of themes](./docs/themes.rst) diff --git a/doc/FAQ.md b/doc/FAQ.md deleted file mode 100644 index e521070..0000000 --- a/doc/FAQ.md +++ /dev/null @@ -1,25 +0,0 @@ -# FAQs - -## My bar doesn't show any background colors - -Please check that you are using i3wm 4.12 or later. Before that, i3wm didn't have background color support for the status bar. - -## Some of the icons don't render correctly - -Please check that you have ![Font Awesome](https://fontawesome.com/) installed (version 4). - -:information_source: The ![Font Awesome](https://fontawesome.com/) is required for all themes that contain icons (because that is the font that includes these icons). Please refer to your distribution's package management on how to install them, or get them from their website directly. Also, please note that Font Awesome removed some icons used by `bumblebee-status` from the free set in version 5, so if possible, stick with 4. - -``` -# Font Awesome installation instructions - -# Arch Linux -$ sudo pacman -S awesome-terminal-fonts - -# FreeBSD -$ sudo pkg install font-awesome -$ sudo pkg install py36-tzlocal py36-pytz py36-netifaces py36-psutil py36-requests #for dependencies - -# Other -# see https://github.com/gabrielelana/awesome-terminal-fonts -``` diff --git a/doc/FEATURES.md b/doc/FEATURES.md deleted file mode 100644 index 4ebd83e..0000000 --- a/doc/FEATURES.md +++ /dev/null @@ -1,89 +0,0 @@ -# Features and advanced usage - -## Events -Many modules provide default handling for various events, for example: - -- Mouse-Wheel on any module moves to the next/previous i3 workspace -- Left-click on the "disk" module opens the specified path in a file browser -- Left-click on either "memory" or "cpu" opens a system monitor -- Left-click on a "pulseaudio" (or pasource/pasink) module toggles the mute state -- Mouse-Wheel up/down on a "pulseaudio" module raises/lowers the volume - -You can provide your own handlers to any module by using the following "special" configuration parameters: - -- left-click -- right-click -- middle-click -- wheel-up -- wheel-down -For example, to execute "pavucontrol" whenever you left-click on the nic module, you could write: - -`$ bumblebee-status -p nic.left-click="pavucontrol"` - -In the string, you can use the following format identifiers: -- name -- instance -- button - -For example: - -`$ bumblebee-status -p disk.left-click="nautilus {instance}"` - -## Update intervals -The general "update interval" is set using the `-i|--interval` parameter of `bumblebee-status`, and defaults to 1 second. -Some modules override this interval to update less frequently (e.g. the kernel version is updated only very rarely, as it -usually doesn't change during runtime). -Also, modules like `weather` or `stock` update less frequently, to avoid hitting API limits. - -For each module, it is possible to specify a parameter `interval` to override that behaviour. - -For example, to update the battery status once per minute, you'd use something like this: - -`$ bumblebee-status -m battery -p battery.interval=1m` - -The format supports: -- numbers (assumed to be seconds - `battery.interval=20` means every 20s) -- `h`, `m`, `s` and combinations thereof - `battery.interval=2m30s` means every 2 minutes, 30 seconds) - -## Errors -If errors occur, you should see them in the i3bar itself. If that does not work, or you need more information for troubleshooting, you can activate a debug log using the `-d` or `--debug` switch: - -``` -$ ./bumblebee-status -d -m -``` - -This will log to stderr, so unless you are running `bumblebee-status` interactively in the CLI, you'll need to specify a logfile using `-f` or `--logfile`. Note that putting `bumblebee-status` into debug mode will show an indicator in the bar to make sure you don't forget to clean up the log file occasionally. - -## Automatically hiding modules -If you want to have a minimal bar that stays out of the way, you can use the `-a` or `--autohide` switch to specify a list of module names. All those modules will only be displayed when (and as long as) their state is either warning or critical (high CPU usage, low disk space, etc.). As long as the module is in a "normal" state and does not require attention, it will remain hidden. -Note that this parameter is specified *in addition* to `-m` (i.e. to autohide the CPU module, you would use `bumblebee-status -m cpu memory traffic -a cpu`). - -## Additional widget themeing -There are a few parameters you can tweak directly from the commandline via `-p` or `--parameters`: -- `.theme.minwidth` sets the minimum width of a module/widget (can be a comma-separated list for multi-widget modules). The parameter can be either an integer (in which case it is taken as "number of characters", or a string, in which case the minwidth is the width of the string (e.g. `-p cpu.minwidth="100.00%"`) -- `.theme.align` sets the alignment (again, can be comma-separated for multi-widget modules) - defaults to `left`, valid values are `left`, `right` and `center` - -An example: -``` -$ bumblebee-status -m sensors2 -p sensors2.theme.minwidth=10,10,10,10 sensors2.theme.align=center,center,left,right -``` - -## Configuration files -Any parameter that can be specified using `-p =` on the commandline, can alternatively be specified in one of the following configuration files: -- ~/.bumblebee-status.conf -- ~/.config/bumblebee-status.conf -- ~/.config/bumblebee-status/config - -These parameters act as **fallback**, so values specified on the commandline take precedence. - -Configuration files have the following format: -``` -[module-parameters] - = -``` - -For example: -``` -[module-parameters] -github.token=abcdefabcdef12345 -``` diff --git a/doc/LIST-OF-MODULES.md b/doc/LIST-OF-MODULES.md deleted file mode 100644 index 391c6a1..0000000 --- a/doc/LIST-OF-MODULES.md +++ /dev/null @@ -1,89 +0,0 @@ -# Table of modules -|Name |Description | -|-----|------------| -|__pulseaudio |Displays volume and mute status and controls for PulseAudio devices. Use wheel up and down to change volume, left click mutes, right click opens pavucontrol.

Aliases: pasink (use this to control output instead of input), pasource

Parameters:
* pulseaudio.autostart: If set to 'true' (default is 'false'), automatically starts the pulseaudio daemon if it is not running
* pulseaudio.percent_change: How much to change volume by when scrolling on the module (default is 2%)
* pulseaudio.limit: Upper limit for setting the volume (default is 0%, which means 'no limit')
Note: If the left and right channels have different volumes, the limit might not be reached exactly.
* pulseaudio.showbars: 1 for showing volume bars, requires --markup=pango;
0 for not showing volume bars (default)

Requires the following executable:
* pulseaudio
* pactl
* pavucontrol | -|amixer |get volume level

Parameters:
* amixer.device: Device to use, defaults to "Master,0"

![amixer](../screenshots/amixer.png) | -|apt |Displays APT package update information (\/\)
Requires the following packages:
* aptitude | -|arch-update |Check updates to Arch Linux.

Requires the following executable:
* checkupdates (from pacman-contrib) | -|battery |Displays battery status, remaining percentage and charging information.

Parameters:
* battery.device : Comma-separated list of battery devices to read information from (defaults to auto for auto-detection)
* battery.warning : Warning threshold in % of remaining charge (defaults to 20)
* battery.critical : Critical threshold in % of remaining charge (defaults to 10)
* battery.showdevice : If set to 'true', add the device name to the widget (defaults to False)
* battery.decorate : If set to 'false', hides additional icons (charging, etc.) (defaults to True)
* battery.showpowerconsumption: If set to 'true', show current power consumption (defaults to False)
* battery.compact-devices : If set to 'true', compacts multiple batteries into a single entry (default to False)

![battery](../screenshots/battery.png) | -|battery-upower |Displays battery status, remaining percentage and charging information.

Parameters:
* battery-upower.warning : Warning threshold in % of remaining charge (defaults to 20)
* battery-upower.critical : Critical threshold in % of remaining charge (defaults to 10)
* battery-upower.showremaining : If set to true (default) shows the remaining time until the batteries are completely discharged | -|bluetooth |Displays bluetooth status (Bluez). Left mouse click launches manager app,
right click toggles bluetooth. Needs dbus-send to toggle bluetooth state.

Parameters:
* bluetooth.device : the device to read state from (default is hci0)
* bluetooth.manager : application to launch on click (blueman-manager)
* bluetooth.dbus_destination : dbus destination (defaults to org.blueman.Mechanism)
* bluetooth.dbus_destination_path : dbus destination path (defaults to /)
* bluetooth.right_click_popup : use popup menu when right-clicked (defaults to True)

![bluetooth](../screenshots/bluetooth.png) | -|bluetooth2 |Displays bluetooth status. Left mouse click launches manager app,
right click toggles bluetooth. Needs dbus-send to toggle bluetooth state and
python-dbus to count the number of connections

Parameters:
* bluetooth.manager : application to launch on click (blueman-manager) | -|brightness |Displays the brightness of a display

Parameters:
* brightness.step: The amount of increase/decrease on scroll in % (defaults to 2)

![brightness](../screenshots/brightness.png) | -|caffeine |Enable/disable automatic screen locking.

Requires the following executables:
* xdg-screensaver
* xdotool
* xprop (as dependency for xdotool)
* notify-send

![caffeine](../screenshots/caffeine.png) | -|cmus |Displays information about the current song in cmus.

Requires the following executable:
* cmus-remote

Parameters:
* cmus.format: Format string for the song information. Tag values can be put in curly brackets (i.e. {artist})
Additional tags:
* {file} - full song file name
* {file1} - song file name without path prefix
if {file} = '/foo/bar.baz', then {file1} = 'bar.baz'
* {file2} - song file name without path prefix and extension suffix
if {file} = '/foo/bar.baz', then {file2} = 'bar'
* cmus.layout: Space-separated list of widgets to add. Possible widgets are the buttons/toggles cmus.prev, cmus.next, cmus.shuffle and cmus.repeat, and the main display with play/pause function cmus.main.
* cmus.server: The address of the cmus server, either a UNIX socket or host[:port]. Connects to the local instance by default.
* cmus.passwd: The password to use for the TCP/IP connection.

![cmus](../screenshots/cmus.png) | -|cpu |Displays CPU utilization across all CPUs.

Parameters:
* cpu.warning : Warning threshold in % of CPU usage (defaults to 70%)
* cpu.critical: Critical threshold in % of CPU usage (defaults to 80%)
* cpu.format : Format string (defaults to '{:.01f}%')

![cpu](../screenshots/cpu.png) | -|cpu2 |Multiwidget CPU module

Can display any combination of:

* max CPU frequency
* total CPU load in percents (integer value)
* per-core CPU load as graph - either mono or colored
* CPU temperature (in Celsius degrees)
* CPU fan speed

Requirements:

* the psutil Python module for the first three items from the list above
* sensors executable for the rest

Parameters:
* cpu2.layout: Space-separated list of widgets to add.
Possible widgets are:
* cpu2.maxfreq
* cpu2.cpuload
* cpu2.coresload
* cpu2.temp
* cpu2.fanspeed
* cpu2.colored: 1 for colored per core load graph, 0 for mono (default)
if this is set to 1, use --markup=pango
* cpu2.temp_pattern: pattern to look for in the output of 'sensors -u';
required if cpu2.temp widged is used
* cpu2.fan_pattern: pattern to look for in the output of 'sensors -u';
required if cpu2.fanspeed widged is used

Note: if you are getting 'n/a' for CPU temperature / fan speed, then you're
lacking the aforementioned pattern settings or they have wrong values. | -|currency |Displays currency exchange rates. Currently, displays currency between GBP and USD/EUR only.

Requires the following python packages:
* requests

Parameters:
* currency.interval: Interval in minutes between updates, default is 1.
* currency.source: Source currency (ex. 'GBP', 'EUR'). Defaults to 'auto', which infers the local one from IP address.
* currency.destination: Comma-separated list of destination currencies (defaults to 'USD,EUR')
* currency.sourceformat: String format for source formatting; Defaults to '{}: {}' and has two variables,
the base symbol and the rate list
* currency.destinationdelimiter: Delimiter used for separating individual rates (defaults to '|')

Note: source and destination names right now must correspond to the names used by the API of https://markets.ft.com

![currency](../screenshots/currency.png) | -|date |Displays the current date and time.

Parameters:
* date.format: strftime()-compatible formatting string
* date.locale: locale to use rather than the system default

![date](../screenshots/date.png) | -|datetime |Displays the current date and time.

Parameters:
* datetime.format: strftime()-compatible formatting string
* datetime.locale: locale to use rather than the system default

![datetime](../screenshots/datetime.png) | -|datetimetz |Displays the current date and time with timezone options.

Parameters:
* datetimetz.format : strftime()-compatible formatting string
* datetimetz.timezone : IANA timezone name
* datetz.format : alias for datetimetz.format
* timetz.format : alias for datetimetz.format
* timetz.timezone : alias for datetimetz.timezone
* datetimetz.locale : locale to use rather than the system default
* datetz.locale : alias for datetimetz.locale
* timetz.locale : alias for datetimetz.locale
* timetz.timezone : alias for datetimetz.timezone | -|datetz |Displays the current date and time.

Parameters:
* date.format: strftime()-compatible formatting string
* date.locale: locale to use rather than the system default | -|deadbeef |Displays the current song being played in DeaDBeeF and provides
some media control bindings.
Left click toggles pause, scroll up skips the current song, scroll
down returns to the previous song.

Requires the following library:
* subprocess
Parameters:
* deadbeef.format: Format string (defaults to '{artist} - {title}')
Available values are: {artist}, {title}, {album}, {length},
{trackno}, {year}, {comment},
{copyright}, {time}
This is deprecated, but much simpler.
* deadbeef.tf_format: A foobar2000 title formatting-style format string.
These can be much more sophisticated than the standard
format strings. This is off by default, but specifying
any tf_format will enable it. If both deadbeef.format
and deadbeef.tf_format are specified, deadbeef.tf_format
takes priority.
* deadbeef.tf_format_if_stopped: Controls whether or not the tf_format format
string should be displayed even if no song is paused or
playing. This could be useful if you want to implement
your own stop strings with the built in logic. Any non-
null value will enable this (by default the module will
hide itself when the player is stopped).
* deadbeef.previous: Change binding for previous song (default is left click)
* deadbeef.next: Change binding for next song (default is right click)
* deadbeef.pause: Change binding for toggling pause (default is middle click)
Available options for deadbeef.previous, deadbeef.next and deadbeef.pause are:
LEFT_CLICK, RIGHT_CLICK, MIDDLE_CLICK, SCROLL_UP, SCROLL_DOWN | -|debug |Shows that debug is enabled | -|deezer |Displays the current song being played
Requires the following library:
* python-dbus
Parameters:
* deezer.format: Format string (defaults to '{artist} - {title}')
Available values are: {album}, {title}, {artist}, {trackNumber}, {playbackStatus}
* deezer.previous: Change binding for previous song (default is left click)
* deezer.next: Change binding for next song (default is right click)
* deezer.pause: Change binding for toggling pause (default is middle click)
Available options for deezer.previous, deezer.next and deezer.pause are:
LEFT_CLICK, RIGHT_CLICK, MIDDLE_CLICK, SCROLL_UP, SCROLL_DOWN | -|disk |Shows free diskspace, total diskspace and the percentage of free disk space.

Parameters:
* disk.warning: Warning threshold in % of disk space (defaults to 80%)
* disk.critical: Critical threshold in % of disk space (defaults ot 90%)
* disk.path: Path to calculate disk usage from (defaults to /)
* disk.open: Which application / file manager to launch (default xdg-open)
* disk.format: Format string, tags {path}, {used}, {left}, {size} and {percent} (defaults to '{path} {used}/{size} ({percent:05.02f}%)')

![disk](../screenshots/disk.png) | -|dnf |Displays DNF package update information (\/\/\/\)

Requires the following executable:
* dnf

Parameters:
* dnf.interval: Time in minutes between two consecutive update checks (defaults to 30 minutes)

![dnf](../screenshots/dnf.png) | -|docker_ps |Displays the number of docker containers running

Requires the following python packages:
* docker | -|dunst |Toggle dunst notifications.

![dunst](../screenshots/dunst.png) | -|error |Shows bumblebee-status errors | -|getcrypto |Displays the price of a cryptocurrency.

Requires the following python packages:
* requests

Parameters:
* getcrypto.interval: Interval in seconds for updating the price, default is 120, less than that will probably get your IP banned.
* getcrypto.getbtc: 0 for not getting price of BTC, 1 for getting it (default).
* getcrypto.geteth: 0 for not getting price of ETH, 1 for getting it (default).
* getcrypto.getltc: 0 for not getting price of LTC, 1 for getting it (default).
* getcrypto.getcur: Set the currency to display the price in, usd is the default.

![getcrypto](../screenshots/getcrypto.png) | -|git |Print the branch and git status for the
currently focused window.

Requires:
* xcwd
* Python module 'pygit2'

![git](../screenshots/git.png) | -|github |Displays the unread GitHub notifications for a GitHub user

Requires the following library:
* requests

Parameters:
* github.token: GitHub user access token, the token needs to have the 'notifications' scope.
* github.interval: Interval in minutes between updates, default is 5.

![github](../screenshots/github.png) | -|gpmdp |Displays information about the current song in Google Play music player.

Requires the following executable:
* gpmdp-remote | -|hddtemp |Fetch hard drive temeperature data from a hddtemp daemon
that runs on localhost and default port (7634) | -|hostname |Displays the system hostname. | -|http_status |Display HTTP status code

Parameters:
* http__status.label: Prefix label (optional)
* http__status.target: Target to retrieve the HTTP status from
* http__status.expect: Expected HTTP status

![http_status](../screenshots/http_status.png) | -|indicator |Displays the indicator status, for numlock, scrolllock and capslock

Parameters:
* indicator.include: Comma-separated list of interface prefixes to include (defaults to 'numlock,capslock')
* indicator.signalstype: If you want the signali type color to be 'critical' or 'warning' (defaults to 'warning')

![indicator](../screenshots/indicator.png) | -|kernel |Shows Linux kernel version information

![kernel](../screenshots/kernel.png) | -|layout |Displays and changes the current keyboard layout

Requires the following executable:
* setxkbmap

![layout](../screenshots/layout.png) | -|layout-xkb |Displays the current keyboard layout using libX11

Requires the following library:
* libX11.so.6
and python module:
* xkbgroup

Parameters:
* layout-xkb.showname: Boolean that indicate whether the full name should be displayed. Defaults to false (only the symbol will be displayed)
* layout-xkb.show_variant: Boolean that indecates whether the variant name should be displayed. Defaults to true. | -|layout-xkbswitch |Displays and changes the current keyboard layout

Requires the following executable:
* xkb-switch | -|libvirtvms |Displays count of running libvirt VMs.
Required the following python packages:
* libvirt | -|load |Displays system load.

Parameters:
* load.warning : Warning threshold for the one-minute load average (defaults to 70% of the number of CPUs)
* load.critical: Critical threshold for the one-minute load average (defaults to 80% of the number of CPUs)

![load](../screenshots/load.png) | -|memory |Displays available RAM, total amount of RAM and percentage available.

Parameters:
* memory.warning : Warning threshold in % of memory used (defaults to 80%)
* memory.critical: Critical threshold in % of memory used (defaults to 90%)
* memory.format: Format string (defaults to '{used}/{total} ({percent:05.02f}%)')
* memory.usedonly: Only show the amount of RAM in use (defaults to False). Same as memory.format='{used}'

![memory](../screenshots/memory.png) | -|mocp |Displays information about the current song in mocp. Left click toggles play/pause. Right click toggles shuffle.

Requires the following executable:
* mocp

Parameters:
* mocp.format: Format string for the song information. Replace string sequences with the actual information:
%state State
%file File
%title Title, includes track, artist, song title and album
%artist Artist
%song SongTitle
%album Album
%tt TotalTime
%tl TimeLeft
%ts TotalSec
%ct CurrentTime
%cs CurrentSec
%b Bitrate
%r Sample rate | -|mpd |Displays information about the current song in mpd.

Requires the following executable:
* mpc

Parameters:
* mpd.format: Format string for the song information.
Supported tags (see `man mpc` for additional information)
* {name}
* {artist}
* {album}
* {albumartist}
* {comment}
* {composer}
* {date}
* {originaldate}
* {disc}
* {genre}
* {performer}
* {title}
* {track}
* {time}
* {file}
* {id}
* {prio}
* {mtime}
* {mdate}
Additional tags:
* {position} - position of currently playing song
not to be confused with %position% mpc tag
* {duration} - duration of currently playing song
* {file1} - song file name without path prefix
if {file} = '/foo/bar.baz', then {file1} = 'bar.baz'
* {file2} - song file name without path prefix and extension suffix
if {file} = '/foo/bar.baz', then {file2} = 'bar'
* mpd.host: MPD host to connect to. (mpc behaviour by default)
* mpd.layout: Space-separated list of widgets to add. Possible widgets are the buttons/toggles mpd.prev, mpd.next, mpd.shuffle and mpd.repeat, and the main display with play/pause function mpd.main.

![mpd](../screenshots/mpd.png) | -|network_traffic |Displays network traffic
* No extra configuration needed | -|nic |Displays the name, IP address(es) and status of each available network interface.

Requires the following python module:
* netifaces

Parameters:
* nic.exclude: Comma-separated list of interface prefixes to exclude (defaults to 'lo,virbr,docker,vboxnet,veth,br')
* nic.include: Comma-separated list of interfaces to include
* nic.states: Comma-separated list of states to show (prefix with '^' to invert - i.e. ^down -\> show all devices that are not in state down)
* nic.format: Format string (defaults to '{intf} {state} {ip} {ssid}')

![nic](../screenshots/nic.png) | -|notmuch_count |Displays the result of a notmuch count query
default : unread emails which path do not contained 'Trash' (notmuch count 'tag:unread AND NOT path:/.*Trash.*/')

Parameters:
* notmuch_count.query: notmuch count query to show result

Errors:
if the notmuch query failed, the shown value is -1

Dependencies:
notmuch (https://notmuchmail.org/) | -|nvidiagpu |Displays GPU name, temperature and memory usage.

Parameters:
* nvidiagpu.format: Format string (defaults to '{name}: {temp}°C %{usedmem}/{totalmem} MiB')
Available values are: {name} {temp} {mem_used} {mem_total} {fanspeed} {clock_gpu} {clock_mem}

Requires nvidia-smi | -|octoprint |Displays the Octorpint status and the printer's bed/tools temperature in the status bar.

Left click opens a popup which shows the bed & tools temperatures and additionally a livestream of the webcam (if enabled).

Parameters:
* octoprint.address : Octoprint address (e.q: http://192.168.1.3)
* octoprint.apitoken : Octorpint API Token (can be obtained from the Octoprint Webinterface)
* octoprint.webcam : Set to True if a webcam is connected (default: False) | -|pacman |Displays update information per repository for pacman.

Parameters:
* pacman.sum: If you prefere displaying updates with a single digit (defaults to 'False')

Requires the following executables:
* fakeroot
* pacman

![pacman](../screenshots/pacman.png) | -|pihole |Displays the pi-hole status (up/down) together with the number of ads that were blocked today
Parameters:
* pihole.address : pi-hole address (e.q: http://192.168.1.3)
* pihole.pwhash : pi-hole webinterface password hash (can be obtained from the /etc/pihole/SetupVars.conf file) | -|ping |Periodically checks the RTT of a configurable host using ICMP echos

Requires the following executable:
* ping

Parameters:
* ping.address : IP address to check
* ping.timeout : Timeout for waiting for a reply (defaults to 5.0)
* ping.probes : Number of probes to send (defaults to 5)
* ping.warning : Threshold for warning state, in seconds (defaults to 1.0)
* ping.critical: Threshold for critical state, in seconds (defaults to 2.0)

![ping](../screenshots/ping.png) | -|pomodoro |Display and run a Pomodoro timer.
Left click to start timer, left click again to pause.
Right click will cancel the timer.

Parameters:
* pomodoro.work: The work duration of timer in minutes (defaults to 25)
* pomodoro.break: The break duration of timer in minutes (defaults to 5)
* pomodoro.format: Timer display format with '%m' and '%s' for minutes and seconds (defaults to '%m:%s')
Examples: '%m min %s sec', '%mm', '', 'timer'
* pomodoro.notify: Notification command to run when timer ends/starts (defaults to nothing)
Example: 'notify-send 'Time up!''. If you want to chain multiple commands,
please use an external wrapper script and invoke that. The module itself does
not support command chaining (see https://github.com/tobi-wan-kenobi/bumblebee-status/issues/532
for a detailled explanation) | -|prime |Displays and changes the current selected prime video card

Left click will call 'sudo prime-select nvidia'
Right click will call 'sudo prime-select nvidia'

Running these commands without a password requires editing your sudoers file
(always use visudo, it's very easy to make a mistake and get locked out of your computer!)

sudo visudo -f /etc/sudoers.d/prime

Then put a line like this in there:

user ALL=(ALL) NOPASSWD: /usr/bin/prime-select

If you can't figure out the sudoers thing, then don't worry, it's still really useful.

Parameters:
* prime.nvidiastring: String to use when nvidia is selected (defaults to 'intel')
* prime.intelstring: String to use when intel is selected (defaults to 'intel')

Requires the following executable:
* prime-select | -|progress |Show progress for cp, mv, dd, ...

Parameters:
* progress.placeholder: Text to display while no process is running (defaults to 'n/a')
* progress.barwidth: Width of the progressbar if it is used (defaults to 8)
* progress.format: Format string (defaults to '{bar} {cmd} {arg}')
Available values are: {bar} {pid} {cmd} {arg} {percentage} {quantity} {speed} {time}
* progress.barfilledchar: Character used to draw the filled part of the bar (defaults to '#'), notice that it can be a string
* progress.baremptychar: Character used to draw the empty part of the bar (defaults to '-'), notice that it can be a string

Requires the following executable:
* progress | -|publicip |Displays public IP address | -|redshift |Displays the current color temperature of redshift

Requires the following executable:
* redshift

Parameters:
* redshift.location : location provider, either of 'auto' (default), 'geoclue2',
'ipinfo' or 'manual'
'auto' uses whatever redshift is configured to do
* redshift.lat : latitude if location is set to 'manual'
* redshift.lon : longitude if location is set to 'manual'

![redshift](../screenshots/redshift.png) | -|rotation |Shows a widget for each connected screen and allows the user to loop through different orientations.

Requires the following executable:
* xrandr | -|rss |RSS news ticker

Fetches rss news items and shows these as a news ticker.
Left-clicking will open the full story in a browser.
New stories are highlighted.

Parameters:
* rss.feeds : Space-separated list of RSS URLs
* rss.length : Maximum length of the module, default is 60 | -|sensors |Displays sensor temperature

Parameters:
* sensors.path: path to temperature file (default /sys/class/thermal/thermal_zone0/temp).
* sensors.json: if set to 'true', interpret sensors.path as JSON 'path' in the output
of 'sensors -j' (i.e. \/\/.../\), for example, path could
be: 'coretemp-isa-00000/Core 0/temp1_input' (defaults to 'false')
* sensors.match: (fallback) Line to match against output of 'sensors -u' (default: temp1_input)
* sensors.match_pattern: (fallback) Line to match against before temperature is read (no default)
* sensors.match_number: (fallback) which of the matches you want (default -1: last match).
* sensors.show_freq: whether to show CPU frequency. (default: true)

![sensors](../screenshots/sensors.png) | -|sensors2 |Displays sensor temperature and CPU frequency

Parameters:

* sensors2.chip: 'sensors -u' compatible filter for chip to display (default to empty - show all chips)
* sensors2.showcpu: Enable or disable CPU frequency display (default: true)
* sensors2.showtemp: Enable or disable temperature display (default: true)
* sensors2.showfan: Enable or disable fan display (default: true)
* sensors2.showother: Enable or display 'other' sensor readings (default: false)
* sensors2.showname: Enable or disable show of sensor name (default: false)
* sensors2.chip_include: Comma-separated list of chip to include (defaults to '' will include all by default, example: 'coretemp,bat')
* sensors2.chip_exclude:Comma separated list of chip to exclude (defaults to '' will exlude none by default)
* sensors2.field_include: Comma separated list of chip to include (defaults to '' will include all by default, example: 'temp,fan')
* sensors2.field_exclude: Comma separated list of chip to exclude (defaults to '' will exclude none by default)
* sensors2.chip_field_exclude: Comma separated list of chip field to exclude (defaults to '' will exclude none by default, example: 'coretemp-isa-0000.temp1,coretemp-isa-0000.fan1')
* sensors2.chip_field_include: Comma-separated list of adaper field to include (defaults to '' will include all by default)

![sensors2](../screenshots/sensors2.png) | -|shell |Execute command in shell and print result

Few command examples:
'ping -c 1 1.1.1.1 | grep -Po '(?\<=time=)\d+(\.\d+)? ms''
'echo 'BTC=$(curl -s rate.sx/1BTC | grep -Po '^\d+')USD''
'curl -s https://wttr.in/London?format=%l+%t+%h+%w'
'pip3 freeze | wc -l'
'any_custom_script.sh | grep arguments'

Parameters:
* shell.command: Command to execute
Use single parentheses if evaluating anything inside (sh-style)
For example shell.command='echo $(date +'%H:%M:%S')'
But NOT shell.command='echo $(date +'%H:%M:%S')'
Second one will be evaluated only once at startup
* shell.interval: Update interval in seconds
(defaults to 1s == every bumblebee-status update)
* shell.async: Run update in async mode. Won't run next thread if
previous one didn't finished yet. Useful for long
running scripts to avoid bumblebee-status freezes
(defaults to False) | -|shortcut |Shows a widget per user-defined shortcut and allows to define the behaviour
when clicking on it.

For more than one shortcut, the commands and labels are strings separated by
a demiliter (; semicolon by default).

For example in order to create two shortcuts labeled A and B with commands
cmdA and cmdB you could do:

./bumblebee-status -m shortcut -p shortcut.cmd='ls;ps' shortcut.label='A;B'

Parameters:
* shortcut.cmds : List of commands to execute
* shortcut.labels: List of widgets' labels (text)
* shortcut.delim : Commands and labels delimiter (; semicolon by default)

![shortcut](../screenshots/shortcut.png) | -|smartstatus |Displays HDD smart status of different drives or all drives

Parameters:
* smartstatus.display: how to display (defaults to 'combined', other choices: 'seperate' or 'singles')
* smartstauts.drives: in the case of singles which drives to display, separated comma list value, multiple accepted (defaults to 'sda', example:'sda,sdc') | -|spaceapi |Displays the state of a Space API endpoint
Space API is an API for hackspaces based on JSON. See spaceapi.io for
an example.

Requires the following libraries:
* requests
* regex

Parameters:
* spaceapi.url: String representation of the api endpoint
* spaceapi.format: Format string for the output

Format Strings:
* Format strings are indicated by double %%
* They represent a leaf in the JSON tree, layers seperated by '.'
* Boolean values can be overwritten by appending '%true%false'
in the format string
* Example: to reference 'open' in '{'state':{'open': true}}'
you would write '%%state.open%%', if you also want
to say 'Open/Closed' depending on the boolean you
would write '%%state.open%Open%Closed%%' | -|spacer |Draws a widget with configurable text content.

Parameters:
* spacer.text: Widget contents (defaults to empty string)

![spacer](../screenshots/spacer.png) | -|spotify |Displays the current song being played
Requires the following library:
* python-dbus
Parameters:
* spotify.format: Format string (defaults to '{artist} - {title}')
Available values are: {album}, {title}, {artist}, {trackNumber}, {playbackStatus}
* spotify.previous: Change binding for previous song (default is left click)
* spotify.next: Change binding for next song (default is right click)
* spotify.pause: Change binding for toggling pause (default is middle click)
Available options for spotify.previous, spotify.next and spotify.pause are:
LEFT_CLICK, RIGHT_CLICK, MIDDLE_CLICK, SCROLL_UP, SCROLL_DOWN

![spotify](../screenshots/spotify.png) | -|stock |Display a stock quote from worldtradingdata.com

Requires the following python packages:
* requests

Parameters:
* stock.symbols : Comma-separated list of symbols to fetch
* stock.change : Should we fetch change in stock value (defaults to True)

![stock](../screenshots/stock.png) | -|sun |Displays sunrise and sunset times

Requires the following python packages:
* requests
* suntime

Parameters:
* cpu.lat : Latitude of your location
* cpu.lon : Longitude of your location | -|system |system module

adds the possibility to
* shutdown
* reboot
the system.

Per default a confirmation dialog is shown before the actual action is performed.

Parameters:
* system.confirm: show confirmation dialog before performing any action (default: true)
* system.reboot: specify a reboot command (defaults to 'reboot')
* system.shutdown: specify a shutdown command (defaults to 'shutdown -h now')
* system.logout: specify a logout command (defaults to 'i3exit logout')
* system.switch_user: specify a command for switching the user (defaults to 'i3exit switch_user')
* system.lock: specify a command for locking the screen (defaults to 'i3exit lock')
* system.suspend: specify a command for suspending (defaults to 'i3exit suspend')
* system.hibernate: specify a command for hibernating (defaults to 'i3exit hibernate') | -|taskwarrior |Displays the number of pending tasks in TaskWarrior.

Requires the following library:
* taskw

Parameters:
* taskwarrior.taskrc : path to the taskrc file (defaults to ~/.taskrc)

![taskwarrior](../screenshots/taskwarrior.png) | -|test |Test module | -|time |Displays the current date and time.

Parameters:
* time.format: strftime()-compatible formatting string
* time.locale: locale to use rather than the system default

![time](../screenshots/time.png) | -|timetz |Displays the current date and time.

Parameters:
* time.format: strftime()-compatible formatting string
* time.locale: locale to use rather than the system default | -|title |Displays focused i3 window title.

Requirements:
* i3ipc

Parameters:
* title.max : Maximum character length for title before truncating. Defaults to 64.
* title.placeholder : Placeholder text to be placed if title was truncated. Defaults to '...'.
* title.scroll : Boolean flag for scrolling title. Defaults to False

![title](../screenshots/title.png) | -|todo |Displays the number of todo items from a text file

Parameters:
* todo.file: File to read TODOs from (defaults to ~/Documents/todo.txt)

![todo](../screenshots/todo.png) | -|traffic |Displays network IO for interfaces.

Parameters:
* traffic.exclude: Comma-separated list of interface prefixes to exclude (defaults to 'lo,virbr,docker,vboxnet,veth')
* traffic.states: Comma-separated list of states to show (prefix with '^' to invert - i.e. ^down -\> show all devices that are not in state down)
* traffic.showname: If set to False, hide network interface name (defaults to True)
* traffic.format: Format string for download/upload speeds.
Defaults to '{:.2f}'
* traffic.graphlen: Graph lenth in seconds. Positive even integer. Each
char shows 2 seconds. If set, enables up/down traffic
graphs

![traffic](../screenshots/traffic.png) | -|twmn |Toggle twmn notifications. | -|uptime |Displays the system uptime.

![uptime](../screenshots/uptime.png) | -|vault |Copy passwords from a password store into the clipboard (currently supports only 'pass')

Many thanks to [@bbernhard](https://github.com/bbernhard) for the idea!

Parameters:
* vault.duration: Duration until password is cleared from clipboard (defaults to 30)
* vault.location: Location of the password store (defaults to ~/.password-store)
* vault.offx: x-axis offset of popup menu (defaults to 0)
* vault.offy: y-axis offset of popup menu (defaults to 0)

![vault](../screenshots/vault.png) | -|vpn |Displays the VPN profile that is currently in use.

Left click opens a popup menu that lists all available VPN profiles and allows to establish
a VPN connection using that profile.

Prerequisites:
* tk python library (usually python-tk or python3-tk, depending on your distribution)
* nmcli needs to be installed and configured properly.
To quickly test, whether nmcli is working correctly, type 'nmcli -g NAME,TYPE,DEVICE con' which
lists all the connection profiles that are configured. Make sure that your VPN profile is in that list!

e.g: to import a openvpn profile via nmcli:
sudo nmcli connection import type openvpn file \ | -|watson |Displays the status of watson (time-tracking tool)

Requires the following executable:
* watson | -|weather |Displays the temperature on the current location based on the ip

Requires the following python packages:
* requests

Parameters:
* weather.location: Set location, defaults to 'auto' for getting location automatically from a web service
If set to a comma-separated list, left-click and right-click can be used to rotate the locations.
Locations should be city names or city ids.
* weather.unit: metric (default), kelvin, imperial
* weather.showcity: If set to true, show location information, otherwise hide it (defaults to true)
* weather.showminmax: If set to true, show the minimum and maximum temperature, otherwise hide it (defaults to false)
* weather.apikey: API key from http://api.openweathermap.org

![weather](../screenshots/weather.png) | -|xkcd |Opens a random xkcd comic in the browser. | -|xrandr |Shows a widget for each connected screen and allows the user to enable/disable screens.

Parameters:
* xrandr.overwrite_i3config: If set to 'true', this module assembles a new i3 config
every time a screen is enabled or disabled by taking the file '~/.config/i3/config.template'
and appending a file '~/.config/i3/config.\' for every screen.
* xrandr.autoupdate: If set to 'false', does *not* invoke xrandr automatically. Instead, the
module will only refresh when displays are enabled or disabled (defaults to true)

Requires the following python module:
* (optional) i3 - if present, the need for updating the widget list is auto-detected

Requires the following executable:
* xrandr

![xrandr](../screenshots/xrandr.png) | -|yubikey |Shows yubikey information

Requires: https://github.com/Yubico/python-yubico

The output indicates that a YubiKey is not connected or it displays
the corresponding serial number. | -|zpool |Displays info about zpools present on the system

Parameters:
* zpool.list: Comma-separated list of zpools to display info for. If empty, info for all zpools
is displayed. (Default: '')
* zpool.format: Format string, tags {name}, {used}, {left}, {size}, {percentfree}, {percentuse},
{status}, {shortstatus}, {fragpercent}, {deduppercent} are supported.
(Default: '{name} {used}/{size} ({percentfree}%)')
* zpool.showio: Show also widgets detailing current read and write I/O (Default: true)
* zpool.ioformat: Format string for I/O widget, tags {ops} (operations per seconds) and {band}
(bandwidth) are supported. (Default: '{band}')
* zpool.warnfree: Warn if free space is below this percentage (Default: 10)
* zpool.sudo: Use sudo when calling the `zpool` binary. (Default: false)

Option `zpool.sudo` is intended for Linux users using zfsonlinux older than 0.7.0: In pre-0.7.0
releases of zfsonlinux regular users couldn't invoke even informative commands such as
`zpool list`. If this option is true, command `zpool list` is invoked with sudo. If this option
is used, the following (or ekvivalent) must be added to the `sudoers(5)`:

```
\ ALL = (root) NOPASSWD: /usr/bin/zpool list
```

Be aware of security implications of doing this!

![zpool](../screenshots/zpool.png) | diff --git a/doc/LIST-OF-THEMES.md b/doc/LIST-OF-THEMES.md deleted file mode 100644 index 29526fd..0000000 --- a/doc/LIST-OF-THEMES.md +++ /dev/null @@ -1,71 +0,0 @@ -# Themes - -Here are some screenshots of various themes: - -:exclamation: Some themes (e.g. all 'powerline' themes) require [Font Awesome](http://fontawesome.io/) and a powerline-compatible font ([powerline-fonts](https://github.com/powerline/fonts). - -:exclamation: If you want to add your own theme, just drop it into `~/.config/bumblebee-status/themes/` - -Gruvbox Powerline (`-t gruvbox-powerline`) (contributed by [@TheEdgeOfRage](https://github.com/TheEdgeOfRage)): - -![Gruvbox Powerline](../screenshots/themes/powerline-gruvbox.png) - -Gruvbox Powerline Light (`-t gruvbox-powerline-light`) (contributed by [freed00m](https://github.com/freed00m)): - -![Gruvbox Powerline Light](../screenshots/themes/gruvbox-powerline-light.png) - -Solarized Powerline (`-t solarized-powerline`): - -![Solarized Powerline](../screenshots/themes/powerline-solarized.png) - -Gruvbox (`-t gruvbox`): - -![Gruvbox](../screenshots/themes/gruvbox.png) - -Gruvbox Light (`-t gruvbox-light`) (contributed by [freed00m](https://github.com/freed00m)): - -![Gruvbox Light](../screenshots/themes/gruvbox-light.png) - -Solarized (`-t solarized`): - -![Solarized](../screenshots/themes/solarized.png) - -Powerline (`-t powerline`): - -![Powerline](../screenshots/themes/powerline.png) - -Greyish Powerline (`-t greyish-powerline`) (contributed by Joshua Bark): - -![Greyish Powerline](../screenshots/themes/powerline-greyish.png) - -Iceberg (`-t iceberg`) (contributed by [whzup](https://github.com/whzup)): - -![Iceberg](../screenshots/themes/iceberg.png) - -Iceberg Powerline (`-t iceberg-powerline`) (contributed by [whzup](https://github.com/whzup)): - -![Iceberg Powerline](../screenshots/themes/iceberg-powerline.png) - -Iceberg Dark Powerline (`-t iceberg-dark-powerline`) (contributed by [gkeep](https://github.com/gkeep)): - -![Iceberg Dark Powerline](../screenshots/themes/iceberg-dark-powerline.png) - -Iceberg Rainbow (`-t iceberg-rainbow`) (contributed by [whzup](https://github.com/whzup)): - -![Iceberg Rainbow](../screenshots/themes/iceberg-rainbow.png) - -Iceberg Contrast (`-t iceberg-contrast`) (contributed by [martindoublem](https://github.com/martindoublem)): - -![Iceberg Contrast](../screenshots/themes/iceberg-contrast.png) - -One Dark Powerline (`-t onedark-powerline`) (contributed by [dillasyx](https://github.com/dillasyx)): - -![One Dark Powerline](../screenshots/themes/onedark-powerline.png) - -Dracula Powerline (-t dracula-powerline) (contributed by [xsteadfastx](https://github.com/xsteadfastx)): - -![Dracula Powerline](../screenshots/themes/dracula-powerline.png) - -Default (nothing or `-t default`): - -![Default](../screenshots/themes/default.png) diff --git a/doc/development/WRITING-A-MODULE.md b/doc/development/WRITING-A-MODULE.md deleted file mode 100644 index 8ef08f2..0000000 --- a/doc/development/WRITING-A-MODULE.md +++ /dev/null @@ -1,130 +0,0 @@ -# Writing a bumblebee-status module - -## Introduction -Adding a new module to `bumblebee-status` is straight-forward: - -- Add a new Python module in `modules/contrib/`. The name of the - module will be the name that the user needs to specify when - invoking `bumblebee-status` (i.e. a module called `modules/contrib/test.py` - will be loaded using `bumblebee-status -m test`) -- See below for how to actually write the module -- Test (run `bumblebee-status` in the CLI) -- Make sure your changes don't break anything: `./coverage.sh` -- If you want to do me favour, run your module through `black -t py34` before submitting - -## Pull requests -The project **gladly** accepts PRs for bugfixes, new functionality, new -modules, etc. -When you feel comfortable with what you've developed, please just open -a PR, somebody will look at it eventually :) Thanks! - -## Coding guidelines -I'm pretty open to whatever style you use, but if it's all the same to you -(and yes, I know that the current codebase is only slowly adapting to this): -- Please favour single quotes for strings (except for docstrings, which are always """) -- For private methods/variables, please use a leading `__` (e.g. `__output` rather than `_output`) - -## Hello world -This example will show "hello world" in the status bar: - -```python -"""Short description""" - -import core.module -import core.widget - -class Module(core.module.Module): - def __init__(self, config): - super().__init__(config, core.widget.Widget(self.full_text)) - - def full_text(self, widgets): - return 'hello world' - -# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4 -``` - -## Of modules and widgets -There are two important concepts for module writers: -- A module is something that offers a single set of coherent functionality -- A module has 1 to n "widgets", which translates to individual blocks in the i3bar - -Very often, this is a 1:1 relationship, and a single module has a single widget. If that's the -case for you, you can stop reading now :) - -Otherwise, you have a number of ways to handle widgets: -- During the `super().init__(...)` inside the module's constructor, you can specify a **list** - of widgets, and those will comprise the widgets (in ordered fashion) -- During runtime, you can set a new list of widgets by using the `self.widgets()` - method of the module - -## Adding widgets at runtime -If you want to add widgets during runtime, please use the `add_widget()` method of the module: - -``` -def do_something(self): - self.add_widget(full_text="my sample text", name="") -``` - -TODO: expand on this - -## Periodic updates -`bumblebee-status` modules have two different ways to update their data: -1. Each interval, the callback registered when the widget was created is called. You can do arbitrarily complex things there -2. Each interval, **before** the widget's callback is invoked, a generic `update(self, widgets)` method is called on the **module** - -Largely, where you want to put your update code is up to you. My observations: -- If you want to change the widgets a module has, you **have** to stick with `update()` -- For simple modules, doing the data update in the widget callback is simplest (see `kernel`, for example) - -## Advanced topics -### Event handlers -The `core.input` module can be used to execute callbacks during mouse events: -```python -import core.module -import core.widget -import core.input - -class Module(core.module.Module): - @core.decorators.every(minutes=60, seconds=20) - def __init__(self, config): - super().__init__(config=config, widgets=) - - core.input.register(widget, button=core.input.LEFT_MOUSE, cmd=) -``` - -The command can be either a CLI tool that will be directly executed (e.g. `cmd='shutdown -h now'`) -or a method that will be executed. The method's signature needs to be: `def (self, event)`, -where "event" is the event data provided by i3wm. - -The full list of possible bindings: -- LEFT_MOUSE -- RIGHT_MOUSE -- MIDDLE_MOUSE -- WHEEL_UP -- WHEEL_UP - -### Setting a default update interval -To change the default update interval, you can use a simple decorator: -```python -import core.module -import core.widget -import core.decorators - -class Module(core.module.Module): - @core.decorators.every(minutes=60, seconds=20) - def __init__(self, config): - super().__init__(config=config, widgets=) -``` - -**NOTE**: This makes the update interval of the module independent of what the -user configures via `-i `! It is still possible to override the module's -interval using `-p .interval=`, however. - -## TODOs -- default update interval -- scrolling -- theme.minwidth -- scrolling decorator -- theme.exclude -- per module update interval -> nice string format -- update via events diff --git a/doc/development/WRITING-A-THEME.md b/doc/development/WRITING-A-THEME.md deleted file mode 100644 index ff01a0a..0000000 --- a/doc/development/WRITING-A-THEME.md +++ /dev/null @@ -1,111 +0,0 @@ -# How to write themes - -## Introduction -`bumblebee-status` themes are simply JSON files that describe various attributes (foreground color, -background color, etc.) of the blocks that make up a status bar. - -It is possible to specify each attribute at various levels: -- For a specific state of a specific module -- For a specific module -- A cycle of attributes (those are cycled through widget-by-widget) -- Default values - -Looking up a value follows the "more specific rather than more generic" approach. In other words, -if a foreground color exists for the "warning" state of module "a", any less specific foreground -color value that **would** match will be ignored. - -Themes are loaded from the following locations: -- `$(BUMBLEBEE_STATUS_BASE_DIR)/themes/` -- `~/.config/bumblebee-status/themes/` - -## Basic structure -A very simple theme file looks like this: -```json -{ - "icons": [ "awesome-fonts" ], - "defaults": { - "fg": "#000000", - "bg": "#ffffff", - "warning": { - "fg": "#ff0000", - "bg": "#ffffff" - } - } -} -``` - -## Icons -Using the `icons` directive, it's possible to reuse icon definitions for multiple themes. -The value of the field is the **basename** of a JSON file located in `$(THEME_DIRECTORY)/icons/`. -The format of the icon file is identical to the theme itself (as the two are essentially just -merged into a single JSON. - -## Color definitions and pyWAL support -`bumblebee-status` supports [github:dylanaraps/pywal](https://github.com/dylanaraps/pywal) definitions. - -To make use of them, simply generate a colorset using pyWAL and reference it in the theme like -this: - -```json -{ - "icons": [ ... ], - "colors": [ "wal" ], - "defaults": { - "critical": { - "fg": "cursor", - "bg": "color5" - }, - "warning": { - "fg": "cursor", - "bg": "color6" - }, - } -} -``` - -Additionally, you can use the `colors` directive to set up named colors for your scheme: - -```json -{ - "icons": [ ... ], - "colors": [ { "red": "#ff0000", "green": "#00ff00", "black": "#000000" } ], - "defaults": { - "critical": { - "fg": "red", - "bg": "black" - } -} -``` - -## Pango support -All values that accept a full text (i.e. the base level, `prefix` and `suffix`) accept a special -attribute `pango` **instead** of all other attributes. In other words, if you specify `pango`, -any other attribute on that level (foreground color, etc.) will be ignored! - -Inside `pango`, you can just specify arbitrary Pango attributes, and those will be applied to a -`` that's automatically enclosing the actual text. - -## Full list of attributes - -(TODO: Add explanation) - -- defaults -- cycle -- icons -- warning -- critical -- fg -- bg -- separator -- padding -- pango -- prefix -- suffix -- default-separators -- separator-block-width -- <module name> -- <state> - -## Examples - -see [github:tobi-wan-kenobi/bumblebee-status/themes](https://github.com/tobi-wan-kenobi/bumblebee-status/tree/master/themes) diff --git a/docs/FAQ.rst b/docs/FAQ.rst new file mode 100644 index 0000000..837ab87 --- /dev/null +++ b/docs/FAQ.rst @@ -0,0 +1,38 @@ +.. contents:: + +FAQs +==== + +My bar doesn’t show any background colors +----------------------------------------- + +Please check that you are using i3wm 4.12 or later. Before that, i3wm +didn’t have background color support for the status bar. + +Some of the icons don’t render correctly +---------------------------------------- + +Please check that you have |Font Awesome| installed (version 4). + +.. note:: The |Font Awesome| is required for all themes that + contain icons (because that is the font that includes these icons). + Please refer to your distribution’s package management on how to install + them, or get them from their website directly. Also, please note that + Font Awesome removed some icons used by ``bumblebee-status`` from the + free set in version 5, so if possible, stick with 4. + +.. code-block:: bash + + # Font Awesome installation instructions + + # Arch Linux + $ sudo pacman -S awesome-terminal-fonts + + # FreeBSD + $ sudo pkg install font-awesome + $ sudo pkg install py36-tzlocal py36-pytz py36-netifaces py36-psutil py36-requests #for dependencies + + # Other + # see https://github.com/gabrielelana/awesome-terminal-fonts + +.. |Font Awesome| image:: https://fontawesome.com/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..043df86 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,52 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'bumblebee-status' +copyright = '2020, tobi-wan-kenobi' +author = 'tobi-wan-kenobi' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 0000000..beea50c --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,16 @@ +Developer's Guide +============================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + module + theme + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/development/module.rst b/docs/development/module.rst new file mode 100644 index 0000000..613c18f --- /dev/null +++ b/docs/development/module.rst @@ -0,0 +1,160 @@ +How to write a new module +========================= + +Introduction +------------ + +Adding a new module to ``bumblebee-status`` is straight-forward: + +- Add a new Python module in ``modules/contrib/``. The name of the + module will be the name that the user needs to specify when invoking + ``bumblebee-status`` (i.e. a module called + ``modules/contrib/test.py`` will be loaded using + ``bumblebee-status -m test``) +- See below for how to actually write the module +- Test (run ``bumblebee-status`` in the CLI) +- Make sure your changes don’t break anything: ``./coverage.sh`` +- If you want to do me favour, run your module through + ``black -t py34`` before submitting + +Pull requests +------------- + +The project **gladly** accepts PRs for bugfixes, new functionality, new +modules, etc. When you feel comfortable with what you’ve developed, +please just open a PR, somebody will look at it eventually :) Thanks! + +Coding guidelines +----------------- + +I’m pretty open to whatever style you use, but if it’s all the same to +you (and yes, I know that the current codebase is only slowly adapting +to this): - Please favour single quotes for strings (except for +docstrings, which are always """) - For private methods/variables, +please use a leading ``__`` (e.g. ``__output`` rather than ``_output``) + +Hello world +----------- + +This example will show “hello world” in the status bar: + +.. code:: python + + """Short description""" + + import core.module + import core.widget + + class Module(core.module.Module): + def __init__(self, config): + super().__init__(config, core.widget.Widget(self.full_text)) + + def full_text(self, widgets): + return 'hello world' + + # vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4 + +Of modules and widgets +---------------------- + +There are two important concepts for module writers: - A module is +something that offers a single set of coherent functionality - A module +has 1 to n “widgets”, which translates to individual blocks in the i3bar + +Very often, this is a 1:1 relationship, and a single module has a single +widget. If that’s the case for you, you can stop reading now :) + +Otherwise, you have a number of ways to handle widgets: - During the +``super().init__(...)`` inside the module’s constructor, you can specify +a **list** of widgets, and those will comprise the widgets (in ordered +fashion) - During runtime, you can set a new list of widgets by using +the ``self.widgets()`` method of the module + +Adding widgets at runtime +------------------------- + +If you want to add widgets during runtime, please use the +``add_widget()`` method of the module: + +:: + + def do_something(self): + self.add_widget(full_text="my sample text", name="") + +TODO: expand on this + +Periodic updates +---------------- + +``bumblebee-status`` modules have two different ways to update their +data: 1. Each interval, the callback registered when the widget was +created is called. You can do arbitrarily complex things there 2. Each +interval, **before** the widget’s callback is invoked, a generic +``update(self, widgets)`` method is called on the **module** + +Largely, where you want to put your update code is up to you. My +observations: - If you want to change the widgets a module has, you +**have** to stick with ``update()`` - For simple modules, doing the data +update in the widget callback is simplest (see ``kernel``, for example) + +Advanced topics +--------------- + +Event handlers +~~~~~~~~~~~~~~ + +The ``core.input`` module can be used to execute callbacks during mouse +events: + +.. code:: python + + import core.module + import core.widget + import core.input + + class Module(core.module.Module): + @core.decorators.every(minutes=60, seconds=20) + def __init__(self, config): + super().__init__(config=config, widgets=) + + core.input.register(widget, button=core.input.LEFT_MOUSE, cmd=) + +The command can be either a CLI tool that will be directly executed +(e.g. ``cmd='shutdown -h now'``) or a method that will be executed. The +method’s signature needs to be: ``def (self, event)``, where +“event” is the event data provided by i3wm. + +The full list of possible bindings: - LEFT_MOUSE - RIGHT_MOUSE - +MIDDLE_MOUSE - WHEEL_UP - WHEEL_UP + +Setting a default update interval +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To change the default update interval, you can use a simple decorator: + +.. code:: python + + import core.module + import core.widget + import core.decorators + + class Module(core.module.Module): + @core.decorators.every(minutes=60, seconds=20) + def __init__(self, config): + super().__init__(config=config, widgets=) + +**NOTE**: This makes the update interval of the module independent of +what the user configures via ``-i ``! It is still possible to +override the module’s interval using ``-p .interval=``, +however. + +TODOs +----- + +- default update interval +- scrolling +- theme.minwidth +- scrolling decorator +- theme.exclude +- per module update interval -> nice string format +- update via events diff --git a/docs/development/theme.rst b/docs/development/theme.rst new file mode 100644 index 0000000..53edad8 --- /dev/null +++ b/docs/development/theme.rst @@ -0,0 +1,132 @@ +How to write a new theme +======================== + +Introduction +------------ + +``bumblebee-status`` themes are simply JSON files that describe various +attributes (foreground color, background color, etc.) of the blocks that +make up a status bar. + +It is possible to specify each attribute at various levels: - For a +specific state of a specific module - For a specific module - A cycle of +attributes (those are cycled through widget-by-widget) - Default values + +Looking up a value follows the “more specific rather than more generic” +approach. In other words, if a foreground color exists for the “warning” +state of module “a”, any less specific foreground color value that +**would** match will be ignored. + +Themes are loaded from the following locations: - +``$(BUMBLEBEE_STATUS_BASE_DIR)/themes/`` - +``~/.config/bumblebee-status/themes/`` + +Basic structure +--------------- + +A very simple theme file looks like this: + +.. code:: json + + { + "icons": [ "awesome-fonts" ], + "defaults": { + "fg": "#000000", + "bg": "#ffffff", + "warning": { + "fg": "#ff0000", + "bg": "#ffffff" + } + } + } + +Icons +----- + +Using the ``icons`` directive, it’s possible to reuse icon definitions +for multiple themes. The value of the field is the **basename** of a +JSON file located in ``$(THEME_DIRECTORY)/icons/``. The format of the +icon file is identical to the theme itself (as the two are essentially +just merged into a single JSON. + +Color definitions and pyWAL support +----------------------------------- + +``bumblebee-status`` supports +`github:dylanaraps/pywal `__ +definitions. + +To make use of them, simply generate a colorset using pyWAL and +reference it in the theme like this: + +.. code:: json + + { + "icons": [ ], + "colors": [ "wal" ], + "defaults": { + "critical": { + "fg": "cursor", + "bg": "color5" + }, + "warning": { + "fg": "cursor", + "bg": "color6" + }, + } + } + +Additionally, you can use the ``colors`` directive to set up named +colors for your scheme: + +.. code:: json + + { + "icons": [ ], + "colors": [ { "red": "#ff0000", "green": "#00ff00", "black": "#000000" } ], + "defaults": { + "critical": { + "fg": "red", + "bg": "black" + } + } + +Pango support +------------- + +All values that accept a full text (i.e. the base level, ``prefix`` and +``suffix``) accept a special attribute ``pango`` **instead** of all +other attributes. In other words, if you specify ``pango``, any other +attribute on that level (foreground color, etc.) will be ignored! + +Inside ``pango``, you can just specify arbitrary Pango attributes, and +those will be applied to a ```` that’s automatically +enclosing the actual text. + +Full list of attributes +----------------------- + +(TODO: Add explanation) + +- defaults +- cycle +- icons +- warning +- critical +- fg +- bg +- separator +- padding +- pango +- prefix +- suffix +- default-separators +- separator-block-width +- +- + +Examples +-------- + +see +`github:tobi-wan-kenobi/bumblebee-status/themes `__ diff --git a/docs/features.rst b/docs/features.rst new file mode 100644 index 0000000..b72fce7 --- /dev/null +++ b/docs/features.rst @@ -0,0 +1,131 @@ +Advanced usage +=========================== + +Events +------ + +Many modules provide default handling for various events, for example: + +- Mouse-Wheel on any module moves to the next/previous i3 workspace +- Left-click on the “disk” module opens the specified path in a file + browser +- Left-click on either “memory” or “cpu” opens a system monitor +- Left-click on a “pulseaudio” (or pasource/pasink) module toggles the + mute state +- Mouse-Wheel up/down on a “pulseaudio” module raises/lowers the volume + +You can provide your own handlers to any module by using the following +“special” configuration parameters: + +- left-click +- right-click +- middle-click +- wheel-up +- wheel-down For example, to execute “pavucontrol” whenever you + left-click on the nic module, you could write: + +``$ bumblebee-status -p nic.left-click="pavucontrol"`` + +In the string, you can use the following format identifiers: - name - +instance - button + +For example: + +``$ bumblebee-status -p disk.left-click="nautilus {instance}"`` + +Update intervals +---------------- + +The general “update interval” is set using the ``-i|--interval`` +parameter of ``bumblebee-status``, and defaults to 1 second. Some +modules override this interval to update less frequently (e.g. the +kernel version is updated only very rarely, as it usually doesn’t change +during runtime). Also, modules like ``weather`` or ``stock`` update less +frequently, to avoid hitting API limits. + +For each module, it is possible to specify a parameter ``interval`` to +override that behaviour. + +For example, to update the battery status once per minute, you’d use +something like this: + +``$ bumblebee-status -m battery -p battery.interval=1m`` + +The format supports: - numbers (assumed to be seconds - +``battery.interval=20`` means every 20s) - ``h``, ``m``, ``s`` and +combinations thereof - ``battery.interval=2m30s`` means every 2 minutes, +30 seconds) + +Errors +------ + +If errors occur, you should see them in the i3bar itself. If that does +not work, or you need more information for troubleshooting, you can +activate a debug log using the ``-d`` or ``--debug`` switch: + +:: + + $ ./bumblebee-status -d -m + +This will log to stderr, so unless you are running ``bumblebee-status`` +interactively in the CLI, you’ll need to specify a logfile using ``-f`` +or ``--logfile``. Note that putting ``bumblebee-status`` into debug mode +will show an indicator in the bar to make sure you don’t forget to clean +up the log file occasionally. + +Automatically hiding modules +---------------------------- + +If you want to have a minimal bar that stays out of the way, you can use +the ``-a`` or ``--autohide`` switch to specify a list of module names. +All those modules will only be displayed when (and as long as) their +state is either warning or critical (high CPU usage, low disk space, +etc.). As long as the module is in a “normal” state and does not require +attention, it will remain hidden. Note that this parameter is specified +*in addition* to ``-m`` (i.e. to autohide the CPU module, you would use +``bumblebee-status -m cpu memory traffic -a cpu``). + +Additional widget themeing +-------------------------- + +There are a few parameters you can tweak directly from the commandline +via ``-p`` or ``--parameters``: - ``.theme.minwidth`` sets +the minimum width of a module/widget (can be a comma-separated list for +multi-widget modules). The parameter can be either an integer (in which +case it is taken as “number of characters”, or a string, in which case +the minwidth is the width of the string +(e.g. ``-p cpu.minwidth="100.00%"``) - ``.theme.align`` sets +the alignment (again, can be comma-separated for multi-widget modules) - +defaults to ``left``, valid values are ``left``, ``right`` and +``center`` + +An example: + +:: + + $ bumblebee-status -m sensors2 -p sensors2.theme.minwidth=10,10,10,10 sensors2.theme.align=center,center,left,right + +Configuration files +------------------- + +Any parameter that can be specified using ``-p =`` on the +commandline, can alternatively be specified in one of the following +configuration files: - ~/.bumblebee-status.conf - +~/.config/bumblebee-status.conf - ~/.config/bumblebee-status/config + +These parameters act as **fallback**, so values specified on the +commandline take precedence. + +Configuration files have the following format: + +:: + + [module-parameters] + = + +For example: + +:: + + [module-parameters] + github.token=abcdefabcdef12345 diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..fa515d7 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,25 @@ +.. bumblebee-status documentation master file, created by + sphinx-quickstart on Mon May 4 08:03:26 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to bumblebee-status's documentation! +============================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + introduction + features + FAQ + modules + themes + development/index + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 0000000..c8b84b7 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,131 @@ +Introduction +================ + +General +---------------- +bumblebee-status is a modular, theme-able status line generator for the +`i3 window manager `__. + +Focus is on: + + - ease of use, sane defaults (no mandatory configuration file) + - custom modules: :doc:`development/module` + - custom themes: :doc:`development/theme` + +I hope you like it and I appreciate any kind of feedback: bug reports, +feature requests, etc. :) + +Thanks a lot! + +Required i3wm version: 4.12+ (in earlier versions, blocks won’t have +background colors) + +Supported Python versions: 3.4, 3.5, 3.6, 3.7, 3.8 + +Supported FontAwesome version: 4 (free version of 5 doesn’t include some +of the icons) + +Example usage: + +.. code-block:: + + bar { + status_command /bumblebee-status \ + -m cpu memory battery time pasink pasource \ + -p time.format="%H:%M" \ + -t solarized + } + +Installation +---------------- + +.. code-block:: + + + # from git (development snapshot) + $ git clone git://github.com/tobi-wan-kenobi/bumblebee-status + + # from AUR: + git clone https://aur.archlinux.org/bumblebee-status.git + cd bumblebee-status + makepkg -sicr + + # from PyPI (thanks @tony): + # will install bumblebee-status into ~/.local/bin/bumblebee-status + pip install --user bumblebee-status + +Dependencies +------------ + +:doc:`development/module` lists the dependencies +(Python modules and external executables) for each module. If you are +not using a module, you don’t need the dependencies. + +Usage +------------ + +Normal usage +~~~~~~~~~~~~ + +In your i3wm configuration, modify the *status_command* for your i3bar +like this: + +.. code-block:: + + bar { + status_command \ + -m \ + -p \ + -t + } + +You can retrieve a list of modules (and their parameters) and themes by +entering: + +.. code-block:: + + $ cd bumblebee-status + $ ./bumblebee-status -l themes + $ ./bumblebee-status -l modules + +To change the update interval, use: + +.. code-block:: + + $ ./bumblebee-status -m -p interval= + +The update interval can also be changed on a per-module basis, like +this: + +.. code-block:: + + $ ./bumblebee-status -m cpu memory -p cpu.interval=5s memory.interval=1m + +All modules can be given “aliases” using ``:``, by +which they can be parametrized, for example: + +.. code-block:: + + $ ./bumblebee-status -m disk:root disk:home -p root.path=/ home.path=/home + +As a simple example, this is what my i3 configuration looks like: + +.. code-block:: + + bar { + font pango:Inconsolata 10 + position top + tray_output none + status_command ~/.i3/bumblebee-status/bumblebee-status -m nic disk:root \ + cpu memory battery date time pasink pasource dnf \ + -p root.path=/ time.format="%H:%M CW %V" date.format="%a, %b %d %Y" \ + -t solarized-powerline + } + +Restart i3wm and - that’s it! + +Examples +--------- + +.. include:: themes.rst + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..2119f51 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/modules.rst b/docs/modules.rst new file mode 100644 index 0000000..c8b64f7 --- /dev/null +++ b/docs/modules.rst @@ -0,0 +1,974 @@ +List of available modules +========================= + ++--------------------+-------------------------------------------------+ +| Name | Description | ++====================+=================================================+ +| \__pulseaudio | Displays volume and mute status and controls | +| | for PulseAudio devices. Use wheel up and down | +| | to change volume, left click mutes, right click | +| | opens pavucontrol.Aliases: pasink (use this to | +| | control output instead of input), | +| | pasourceParameters: \* pulseaudio.autostart: If | +| | set to ‘true’ (default is ‘false’), | +| | automatically starts the pulseaudio daemon if | +| | it is not running \* pulseaudio.percent_change: | +| | How much to change volume by when scrolling on | +| | the module (default is 2%) \* pulseaudio.limit: | +| | Upper limit for setting the volume (default is | +| | 0%, which means ‘no limit’) Note: If the left | +| | and right channels have different volumes, the | +| | limit might not be reached exactly. \* | +| | pulseaudio.showbars: 1 for showing volume bars, | +| | requires –markup=pango; 0 for not showing | +| | volume bars (default)Requires the following | +| | executable: \* pulseaudio \* pactl \* | +| | pavucontrol | ++--------------------+-------------------------------------------------+ + +\|amixer \|get volume levelParameters: \* amixer.device: Device to use, +defaults to “Master,0” + +.. raw:: html + +

+ +.. raw:: html + +

+ +|amixer| \| \|apt \|Displays APT package update information (/)Requires the following packages: \* aptitude \| +\|arch-update \|Check updates to Arch Linux.Requires the following +executable: \* checkupdates (from pacman-contrib) \| \|battery +\|Displays battery status, remaining percentage and charging +information.Parameters: \* battery.device : Comma-separated list of +battery devices to read information from (defaults to auto for +auto-detection) \* battery.warning : Warning threshold in % of remaining +charge (defaults to 20) \* battery.critical : Critical threshold in % of +remaining charge (defaults to 10) \* battery.showdevice : If set to +‘true’, add the device name to the widget (defaults to False) \* +battery.decorate : If set to ‘false’, hides additional icons (charging, +etc.) (defaults to True) \* battery.showpowerconsumption: If set to +‘true’, show current power consumption (defaults to False) \* +battery.compact-devices : If set to ‘true’, compacts multiple batteries +into a single entry (default to False) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|battery| \| \|battery-upower \|Displays battery status, remaining +percentage and charging information.Parameters: \* +battery-upower.warning : Warning threshold in % of remaining charge +(defaults to 20) \* battery-upower.critical : Critical threshold in % of +remaining charge (defaults to 10) \* battery-upower.showremaining : If +set to true (default) shows the remaining time until the batteries are +completely discharged \| \|bluetooth \|Displays bluetooth status +(Bluez). Left mouse click launches manager app,right click toggles +bluetooth. Needs dbus-send to toggle bluetooth state.Parameters: \* +bluetooth.device : the device to read state from (default is hci0) \* +bluetooth.manager : application to launch on click (blueman-manager) \* +bluetooth.dbus_destination : dbus destination (defaults to +org.blueman.Mechanism) \* bluetooth.dbus_destination_path : dbus +destination path (defaults to /) \* bluetooth.right_click_popup : use +popup menu when right-clicked (defaults to True) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|bluetooth| \| \|bluetooth2 \|Displays bluetooth status. Left mouse +click launches manager app,right click toggles bluetooth. Needs +dbus-send to toggle bluetooth state andpython-dbus to count the number +of connectionsParameters: \* bluetooth.manager : application to launch +on click (blueman-manager) \| \|brightness \|Displays the brightness of +a displayParameters: \* brightness.step: The amount of increase/decrease +on scroll in % (defaults to 2) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|brightness| \| \|caffeine \|Enable/disable automatic screen +locking.Requires the following executables: \* xdg-screensaver \* +xdotool \* xprop (as dependency for xdotool) \* notify-send + +.. raw:: html + +

+ +.. raw:: html + +

+ +|caffeine| \| \|cmus \|Displays information about the current song in +cmus.Requires the following executable: \* cmus-remoteParameters: \* +cmus.format: Format string for the song information. Tag values can be +put in curly brackets (i.e. {artist}) Additional tags: \* {file} - full +song file name \* {file1} - song file name without path prefix if {file} += ‘/foo/bar.baz’, then {file1} = ‘bar.baz’ \* {file2} - song file name +without path prefix and extension suffix if {file} = ‘/foo/bar.baz’, +then {file2} = ‘bar’ \* cmus.layout: Space-separated list of widgets to +add. Possible widgets are the buttons/toggles cmus.prev, cmus.next, +cmus.shuffle and cmus.repeat, and the main display with play/pause +function cmus.main. \* cmus.server: The address of the cmus server, +either a UNIX socket or host[:port]. Connects to the local instance by +default. \* cmus.passwd: The password to use for the TCP/IP connection. + +.. raw:: html + +

+ +.. raw:: html + +

+ +|cmus| \| \|cpu \|Displays CPU utilization across all CPUs.Parameters: +\* cpu.warning : Warning threshold in % of CPU usage (defaults to 70%) +\* cpu.critical: Critical threshold in % of CPU usage (defaults to 80%) +\* cpu.format : Format string (defaults to ‘{:.01f}%’) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|cpu| \| \|cpu2 \|Multiwidget CPU moduleCan display any combination of: +\* max CPU frequency \* total CPU load in percents (integer value) \* +per-core CPU load as graph - either mono or colored \* CPU temperature +(in Celsius degrees) \* CPU fan speedRequirements: \* the psutil Python +module for the first three items from the list above \* sensors +executable for the restParameters: \* cpu2.layout: Space-separated list +of widgets to add. Possible widgets are: \* cpu2.maxfreq \* cpu2.cpuload +\* cpu2.coresload \* cpu2.temp \* cpu2.fanspeed \* cpu2.colored: 1 for +colored per core load graph, 0 for mono (default) if this is set to 1, +use –markup=pango \* cpu2.temp_pattern: pattern to look for in the +output of ‘sensors -u’; required if cpu2.temp widged is used \* +cpu2.fan_pattern: pattern to look for in the output of ‘sensors -u’; +required if cpu2.fanspeed widged is usedNote: if you are getting ‘n/a’ +for CPU temperature / fan speed, then you’relacking the aforementioned +pattern settings or they have wrong values. \| \|currency \|Displays +currency exchange rates. Currently, displays currency between GBP and +USD/EUR only.Requires the following python packages: \* +requestsParameters: \* currency.interval: Interval in minutes between +updates, default is 1. \* currency.source: Source currency (ex. ‘GBP’, +‘EUR’). Defaults to ‘auto’, which infers the local one from IP address. +\* currency.destination: Comma-separated list of destination currencies +(defaults to ‘USD,EUR’) \* currency.sourceformat: String format for +source formatting; Defaults to ‘{}: {}’ and has two variables, the base +symbol and the rate list \* currency.destinationdelimiter: Delimiter +used for separating individual rates (defaults to ‘\|’)Note: source and +destination names right now must correspond to the names used by the API +of https://markets.ft.com + +.. raw:: html + +

+ +.. raw:: html + +

+ +|currency| \| \|date \|Displays the current date and time.Parameters: \* +date.format: strftime()-compatible formatting string \* date.locale: +locale to use rather than the system default + +.. raw:: html + +

+ +.. raw:: html + +

+ +|date| \| \|datetime \|Displays the current date and time.Parameters: \* +datetime.format: strftime()-compatible formatting string \* +datetime.locale: locale to use rather than the system default + +.. raw:: html + +

+ +.. raw:: html + +

+ +|datetime| \| \|datetimetz \|Displays the current date and time with +timezone options.Parameters: \* datetimetz.format : +strftime()-compatible formatting string \* datetimetz.timezone : IANA +timezone name \* datetz.format : alias for datetimetz.format \* +timetz.format : alias for datetimetz.format \* timetz.timezone : alias +for datetimetz.timezone \* datetimetz.locale : locale to use rather than +the system default \* datetz.locale : alias for datetimetz.locale \* +timetz.locale : alias for datetimetz.locale \* timetz.timezone : alias +for datetimetz.timezone \| \|datetz \|Displays the current date and +time.Parameters: \* date.format: strftime()-compatible formatting string +\* date.locale: locale to use rather than the system default \| +\|deadbeef \|Displays the current song being played in DeaDBeeF and +providessome media control bindings.Left click toggles pause, scroll up +skips the current song, scrolldown returns to the previous song.Requires +the following library: \* subprocessParameters: \* deadbeef.format: +Format string (defaults to ‘{artist} - {title}’) Available values are: +{artist}, {title}, {album}, {length}, {trackno}, {year}, {comment}, +{copyright}, {time} This is deprecated, but much simpler. \* +deadbeef.tf_format: A foobar2000 title formatting-style format string. +These can be much more sophisticated than the standard format strings. +This is off by default, but specifying any tf_format will enable it. If +both deadbeef.format and deadbeef.tf_format are specified, +deadbeef.tf_format takes priority. \* deadbeef.tf_format_if_stopped: +Controls whether or not the tf_format format string should be displayed +even if no song is paused or playing. This could be useful if you want +to implement your own stop strings with the built in logic. Any non- +null value will enable this (by default the module will hide itself when +the player is stopped). \* deadbeef.previous: Change binding for +previous song (default is left click) \* deadbeef.next: Change binding +for next song (default is right click) \* deadbeef.pause: Change binding +for toggling pause (default is middle click) Available options for +deadbeef.previous, deadbeef.next and deadbeef.pause are: LEFT_CLICK, +RIGHT_CLICK, MIDDLE_CLICK, SCROLL_UP, SCROLL_DOWN \| \|debug \|Shows +that debug is enabled \| \|deezer \|Displays the current song being +playedRequires the following library: \* python-dbusParameters: \* +deezer.format: Format string (defaults to ‘{artist} - {title}’) +Available values are: {album}, {title}, {artist}, {trackNumber}, +{playbackStatus} \* deezer.previous: Change binding for previous song +(default is left click) \* deezer.next: Change binding for next song +(default is right click) \* deezer.pause: Change binding for toggling +pause (default is middle click) Available options for deezer.previous, +deezer.next and deezer.pause are: LEFT_CLICK, RIGHT_CLICK, MIDDLE_CLICK, +SCROLL_UP, SCROLL_DOWN \| \|disk \|Shows free diskspace, total diskspace +and the percentage of free disk space.Parameters: \* disk.warning: +Warning threshold in % of disk space (defaults to 80%) \* disk.critical: +Critical threshold in % of disk space (defaults ot 90%) \* disk.path: +Path to calculate disk usage from (defaults to /) \* disk.open: Which +application / file manager to launch (default xdg-open) \* disk.format: +Format string, tags {path}, {used}, {left}, {size} and {percent} +(defaults to ‘{path} {used}/{size} ({percent:05.02f}%)’) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|disk| \| \|dnf \|Displays DNF package update information +(///)Requires the following +executable: \* dnfParameters: \* dnf.interval: Time in minutes between +two consecutive update checks (defaults to 30 minutes) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|dnf| \| \|docker_ps \|Displays the number of docker containers +runningRequires the following python packages: \* docker \| \|dunst +\|Toggle dunst notifications. + +.. raw:: html + +

+ +.. raw:: html + +

+ +|dunst| \| \|error \|Shows bumblebee-status errors \| \|getcrypto +\|Displays the price of a cryptocurrency.Requires the following python +packages: \* requestsParameters: \* getcrypto.interval: Interval in +seconds for updating the price, default is 120, less than that will +probably get your IP banned. \* getcrypto.getbtc: 0 for not getting +price of BTC, 1 for getting it (default). \* getcrypto.geteth: 0 for not +getting price of ETH, 1 for getting it (default). \* getcrypto.getltc: 0 +for not getting price of LTC, 1 for getting it (default). \* +getcrypto.getcur: Set the currency to display the price in, usd is the +default. + +.. raw:: html + +

+ +.. raw:: html + +

+ +|getcrypto| \| \|git \|Print the branch and git status for thecurrently +focused window.Requires: \* xcwd \* Python module ‘pygit2’ + +.. raw:: html + +

+ +.. raw:: html + +

+ +|git| \| \|github \|Displays the unread GitHub notifications for a +GitHub userRequires the following library: \* requestsParameters: \* +github.token: GitHub user access token, the token needs to have the +‘notifications’ scope. \* github.interval: Interval in minutes between +updates, default is 5. + +.. raw:: html + +

+ +.. raw:: html + +

+ +|github| \| \|gpmdp \|Displays information about the current song in +Google Play music player.Requires the following executable: \* +gpmdp-remote \| \|hddtemp \|Fetch hard drive temeperature data from a +hddtemp daemonthat runs on localhost and default port (7634) \| +\|hostname \|Displays the system hostname. \| \|http_status \|Display +HTTP status codeParameters: \* http__status.label: Prefix label +(optional) \* http__status.target: Target to retrieve the HTTP status +from \* http__status.expect: Expected HTTP status + +.. raw:: html + +

+ +.. raw:: html + +

+ +|http_status| \| \|indicator \|Displays the indicator status, for +numlock, scrolllock and capslock Parameters: \* indicator.include: +Comma-separated list of interface prefixes to include (defaults to +‘numlock,capslock’) \* indicator.signalstype: If you want the signali +type color to be ‘critical’ or ‘warning’ (defaults to ‘warning’) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|indicator| \| \|kernel \|Shows Linux kernel version information + +.. raw:: html + +

+ +.. raw:: html + +

+ +|kernel| \| \|layout \|Displays and changes the current keyboard +layoutRequires the following executable: \* setxkbmap + +.. raw:: html + +

+ +.. raw:: html + +

+ +|layout| \| \|layout-xkb \|Displays the current keyboard layout using +libX11Requires the following library: \* libX11.so.6and python module: +\* xkbgroupParameters: \* layout-xkb.showname: Boolean that indicate +whether the full name should be displayed. Defaults to false (only the +symbol will be displayed) \* layout-xkb.show_variant: Boolean that +indecates whether the variant name should be displayed. Defaults to +true. \| \|layout-xkbswitch \|Displays and changes the current keyboard +layoutRequires the following executable: \* xkb-switch \| \|libvirtvms +\|Displays count of running libvirt VMs.Required the following python +packages: \* libvirt \| \|load \|Displays system load.Parameters: \* +load.warning : Warning threshold for the one-minute load average +(defaults to 70% of the number of CPUs) \* load.critical: Critical +threshold for the one-minute load average (defaults to 80% of the number +of CPUs) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|load| \| \|memory \|Displays available RAM, total amount of RAM and +percentage available.Parameters: \* memory.warning : Warning threshold +in % of memory used (defaults to 80%) \* memory.critical: Critical +threshold in % of memory used (defaults to 90%) \* memory.format: Format +string (defaults to ‘{used}/{total} ({percent:05.02f}%)’) \* +memory.usedonly: Only show the amount of RAM in use (defaults to False). +Same as memory.format=‘{used}’ + +.. raw:: html + +

+ +.. raw:: html + +

+ +|memory| \| \|mocp \|Displays information about the current song in +mocp. Left click toggles play/pause. Right click toggles +shuffle.Requires the following executable: \* mocpParameters: \* +mocp.format: Format string for the song information. Replace string +sequences with the actual information: %state State %file File %title +Title, includes track, artist, song title and album %artist Artist %song +SongTitle %album Album %tt TotalTime %tl TimeLeft %ts TotalSec %ct +CurrentTime %cs CurrentSec %b Bitrate %r Sample rate \| \|mpd \|Displays +information about the current song in mpd.Requires the following +executable: \* mpcParameters: \* mpd.format: Format string for the song +information. Supported tags (see ``man mpc`` for additional information) +\* {name} \* {artist} \* {album} \* {albumartist} \* {comment} \* +{composer} \* {date} \* {originaldate} \* {disc} \* {genre} \* +{performer} \* {title} \* {track} \* {time} \* {file} \* {id} \* {prio} +\* {mtime} \* {mdate} Additional tags: \* {position} - position of +currently playing song not to be confused with %position% mpc tag \* +{duration} - duration of currently playing song \* {file1} - song file +name without path prefix if {file} = ‘/foo/bar.baz’, then {file1} = +‘bar.baz’ \* {file2} - song file name without path prefix and extension +suffix if {file} = ‘/foo/bar.baz’, then {file2} = ‘bar’ \* mpd.host: MPD +host to connect to. (mpc behaviour by default) \* mpd.layout: +Space-separated list of widgets to add. Possible widgets are the +buttons/toggles mpd.prev, mpd.next, mpd.shuffle and mpd.repeat, and the +main display with play/pause function mpd.main. + +.. raw:: html + +

+ +.. raw:: html + +

+ +|mpd| \| \|network_traffic \|Displays network traffic\* No extra +configuration needed \| \|nic \|Displays the name, IP address(es) and +status of each available network interface.Requires the following python +module: \* netifacesParameters: \* nic.exclude: Comma-separated list of +interface prefixes to exclude (defaults to +‘lo,virbr,docker,vboxnet,veth,br’) \* nic.include: Comma-separated list +of interfaces to include \* nic.states: Comma-separated list of states +to show (prefix with ‘^’ to invert - i.e. ^down -> show all devices that +are not in state down) \* nic.format: Format string (defaults to ‘{intf} +{state} {ip} {ssid}’) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|nic| \| \|notmuch_count \|Displays the result of a notmuch count query +default : unread emails which path do not contained ‘Trash’ (notmuch +count ‘tag:unread AND NOT path:/.\ *Trash.*/’)Parameters: \* +notmuch_count.query: notmuch count query to show result Errors: if the +notmuch query failed, the shown value is -1Dependencies: notmuch +(https://notmuchmail.org/) \| \|nvidiagpu \|Displays GPU name, +temperature and memory usage.Parameters: \* nvidiagpu.format: Format +string (defaults to ‘{name}: {temp}°C %{usedmem}/{totalmem} MiB’) +Available values are: {name} {temp} {mem_used} {mem_total} {fanspeed} +{clock_gpu} {clock_mem}Requires nvidia-smi \| \|octoprint \|Displays the +Octorpint status and the printer’s bed/tools temperature in the status +bar. Left click opens a popup which shows the bed & tools temperatures +and additionally a livestream of the webcam (if enabled).Parameters: \* +octoprint.address : Octoprint address (e.q: http://192.168.1.3) \* +octoprint.apitoken : Octorpint API Token (can be obtained from the +Octoprint Webinterface) \* octoprint.webcam : Set to True if a webcam is +connected (default: False) \| \|pacman \|Displays update information per +repository for pacman.Parameters: \* pacman.sum: If you prefere +displaying updates with a single digit (defaults to ‘False’)Requires the +following executables: \* fakeroot \* pacman + +.. raw:: html + +

+ +.. raw:: html + +

+ +|pacman| \| \|pihole \|Displays the pi-hole status (up/down) together +with the number of ads that were blocked todayParameters: \* +pihole.address : pi-hole address (e.q: http://192.168.1.3) \* +pihole.pwhash : pi-hole webinterface password hash (can be obtained from +the /etc/pihole/SetupVars.conf file) \| \|ping \|Periodically checks the +RTT of a configurable host using ICMP echosRequires the following +executable: \* pingParameters: \* ping.address : IP address to check \* +ping.timeout : Timeout for waiting for a reply (defaults to 5.0) \* +ping.probes : Number of probes to send (defaults to 5) \* ping.warning : +Threshold for warning state, in seconds (defaults to 1.0) \* +ping.critical: Threshold for critical state, in seconds (defaults to +2.0) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|ping| \| \|pomodoro \|Display and run a Pomodoro timer.Left click to +start timer, left click again to pause.Right click will cancel the +timer.Parameters: \* pomodoro.work: The work duration of timer in +minutes (defaults to 25) \* pomodoro.break: The break duration of timer +in minutes (defaults to 5) \* pomodoro.format: Timer display format with +‘%m’ and ‘%s’ for minutes and seconds (defaults to ‘%m:%s’) Examples: +‘%m min %s sec’, ‘%mm’, ’‘, ’timer’ \* pomodoro.notify: Notification +command to run when timer ends/starts (defaults to nothing) Example: +‘notify-send ’Time up!’‘. If you want to chain multiple commands, please +use an external wrapper script and invoke that. The module itself does +not support command chaining (see +https://github.com/tobi-wan-kenobi/bumblebee-status/issues/532 for a +detailled explanation) \| \|prime \|Displays and changes the current +selected prime video cardLeft click will call ’sudo prime-select +nvidia’Right click will call ‘sudo prime-select nvidia’Running these +commands without a password requires editing your sudoers file(always +use visudo, it’s very easy to make a mistake and get locked out of your +computer!)sudo visudo -f /etc/sudoers.d/primeThen put a line like this +in there: user ALL=(ALL) NOPASSWD: /usr/bin/prime-selectIf you can’t +figure out the sudoers thing, then don’t worry, it’s still really +useful.Parameters: \* prime.nvidiastring: String to use when nvidia is +selected (defaults to ‘intel’) \* prime.intelstring: String to use when +intel is selected (defaults to ‘intel’)Requires the following +executable: \* prime-select \| \|progress \|Show progress for cp, mv, +dd, …Parameters: \* progress.placeholder: Text to display while no +process is running (defaults to ‘n/a’) \* progress.barwidth: Width of +the progressbar if it is used (defaults to 8) \* progress.format: Format +string (defaults to ‘{bar} {cmd} {arg}’) Available values are: {bar} +{pid} {cmd} {arg} {percentage} {quantity} {speed} {time} \* +progress.barfilledchar: Character used to draw the filled part of the +bar (defaults to ‘#’), notice that it can be a string \* +progress.baremptychar: Character used to draw the empty part of the bar +(defaults to ‘-’), notice that it can be a stringRequires the following +executable: \* progress \| \|publicip \|Displays public IP address \| +\|redshift \|Displays the current color temperature of redshiftRequires +the following executable: \* redshiftParameters: \* redshift.location : +location provider, either of ‘auto’ (default), ‘geoclue2’, ‘ipinfo’ or +‘manual’ ‘auto’ uses whatever redshift is configured to do \* +redshift.lat : latitude if location is set to ‘manual’ \* redshift.lon : +longitude if location is set to ‘manual’ + +.. raw:: html + +

+ +.. raw:: html + +

+ +|redshift| \| \|rotation \|Shows a widget for each connected screen and +allows the user to loop through different orientations.Requires the +following executable: \* xrandr \| \|rss \|RSS news tickerFetches rss +news items and shows these as a news ticker.Left-clicking will open the +full story in a browser.New stories are highlighted.Parameters: \* +rss.feeds : Space-separated list of RSS URLs \* rss.length : Maximum +length of the module, default is 60 \| \|sensors \|Displays sensor +temperatureParameters: \* sensors.path: path to temperature file +(default /sys/class/thermal/thermal_zone0/temp). \* sensors.json: if set +to ‘true’, interpret sensors.path as JSON ‘path’ in the output of +‘sensors -j’ (i.e. //…/), for example, path could be: +‘coretemp-isa-00000/Core 0/temp1_input’ (defaults to ‘false’) \* +sensors.match: (fallback) Line to match against output of ‘sensors -u’ +(default: temp1_input) \* sensors.match_pattern: (fallback) Line to +match against before temperature is read (no default) \* +sensors.match_number: (fallback) which of the matches you want (default +-1: last match). \* sensors.show_freq: whether to show CPU frequency. +(default: true) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|sensors| \| \|sensors2 \|Displays sensor temperature and CPU +frequencyParameters: \* sensors2.chip: ‘sensors -u’ compatible filter +for chip to display (default to empty - show all chips) \* +sensors2.showcpu: Enable or disable CPU frequency display (default: +true) \* sensors2.showtemp: Enable or disable temperature display +(default: true) \* sensors2.showfan: Enable or disable fan display +(default: true) \* sensors2.showother: Enable or display ‘other’ sensor +readings (default: false) \* sensors2.showname: Enable or disable show +of sensor name (default: false) \* sensors2.chip_include: +Comma-separated list of chip to include (defaults to ’’ will include all +by default, example: ‘coretemp,bat’) \* sensors2.chip_exclude:Comma +separated list of chip to exclude (defaults to ’’ will exlude none by +default) \* sensors2.field_include: Comma separated list of chip to +include (defaults to ’’ will include all by default, example: +‘temp,fan’) \* sensors2.field_exclude: Comma separated list of chip to +exclude (defaults to ’’ will exclude none by default) \* +sensors2.chip_field_exclude: Comma separated list of chip field to +exclude (defaults to ’’ will exclude none by default, example: +‘coretemp-isa-0000.temp1,coretemp-isa-0000.fan1’) \* +sensors2.chip_field_include: Comma-separated list of adaper field to +include (defaults to ’’ will include all by default) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|sensors2| \| \|shell \|Execute command in shell and print resultFew +command examples: ‘ping -c 1 1.1.1.1 \| grep +-Po’(?<=time=):raw-latex:`\d+`(.:raw-latex:`\d+`)? ms’‘ ’echo +’BTC=$(curl -s rate.sx/1BTC \| grep -Po’^:raw-latex:`\d+`‘)USD’‘ ’curl +-s https://wttr.in/London?format=%l+%t+%h+%w’ ‘pip3 freeze \| wc -l’ +‘any_custom_script.sh \| grep arguments’Parameters: \* shell.command: +Command to execute Use single parentheses if evaluating anything inside +(sh-style) For example shell.command=‘echo $(date +’%H:%M:%S’)‘ But NOT +shell.command=’echo $(date +’%H:%M:%S’)‘ Second one will be evaluated +only once at startup \* shell.interval: Update interval in seconds +(defaults to 1s == every bumblebee-status update) \* shell.async: Run +update in async mode. Won’t run next thread if previous one didn’t +finished yet. Useful for long running scripts to avoid bumblebee-status +freezes (defaults to False) \| \|shortcut \|Shows a widget per +user-defined shortcut and allows to define the behaviourwhen clicking on +it.For more than one shortcut, the commands and labels are strings +separated bya demiliter (; semicolon by default).For example in order to +create two shortcuts labeled A and B with commandscmdA and cmdB you +could do: ./bumblebee-status -m shortcut -p shortcut.cmd=’ls;ps’ +shortcut.label=‘A;B’Parameters: \* shortcut.cmds : List of commands to +execute \* shortcut.labels: List of widgets’ labels (text) \* +shortcut.delim : Commands and labels delimiter (; semicolon by default) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|shortcut| \| \|smartstatus \|Displays HDD smart status of different +drives or all drivesParameters: \* smartstatus.display: how to display +(defaults to ‘combined’, other choices: ‘seperate’ or ‘singles’) \* +smartstauts.drives: in the case of singles which drives to display, +separated comma list value, multiple accepted (defaults to ‘sda’, +example:‘sda,sdc’) \| \|spaceapi \|Displays the state of a Space API +endpointSpace API is an API for hackspaces based on JSON. See +spaceapi.io foran example.Requires the following libraries: \* requests +\* regexParameters: \* spaceapi.url: String representation of the api +endpoint \* spaceapi.format: Format string for the outputFormat Strings: +\* Format strings are indicated by double %% \* They represent a leaf in +the JSON tree, layers seperated by ‘.’ \* Boolean values can be +overwritten by appending ‘%true%false’ in the format string \* Example: +to reference ‘open’ in ‘{’state’:{‘open’: true}}‘ you would +write’%%state.open%%‘, if you also want to say ’Open/Closed’ depending +on the boolean you would write ‘%%state.open%Open%Closed%%’ \| \|spacer +\|Draws a widget with configurable text content.Parameters: \* +spacer.text: Widget contents (defaults to empty string) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|spacer| \| \|spotify \|Displays the current song being playedRequires +the following library: \* python-dbusParameters: \* spotify.format: +Format string (defaults to ‘{artist} - {title}’) Available values are: +{album}, {title}, {artist}, {trackNumber}, {playbackStatus} \* +spotify.previous: Change binding for previous song (default is left +click) \* spotify.next: Change binding for next song (default is right +click) \* spotify.pause: Change binding for toggling pause (default is +middle click) Available options for spotify.previous, spotify.next and +spotify.pause are: LEFT_CLICK, RIGHT_CLICK, MIDDLE_CLICK, SCROLL_UP, +SCROLL_DOWN + +.. raw:: html + +

+ +.. raw:: html + +

+ +|spotify| \| \|stock \|Display a stock quote from +worldtradingdata.comRequires the following python packages: \* +requestsParameters: \* stock.symbols : Comma-separated list of symbols +to fetch \* stock.change : Should we fetch change in stock value +(defaults to True) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|stock| \| \|sun \|Displays sunrise and sunset timesRequires the +following python packages: \* requests \* suntimeParameters: \* cpu.lat +: Latitude of your location \* cpu.lon : Longitude of your location \| +\|system \|system moduleadds the possibility to \* shutdown \* rebootthe +system. Per default a confirmation dialog is shown before the actual +action is performed. Parameters: \* system.confirm: show confirmation +dialog before performing any action (default: true) \* system.reboot: +specify a reboot command (defaults to ‘reboot’) \* system.shutdown: +specify a shutdown command (defaults to ‘shutdown -h now’) \* +system.logout: specify a logout command (defaults to ‘i3exit logout’) \* +system.switch_user: specify a command for switching the user (defaults +to ‘i3exit switch_user’) \* system.lock: specify a command for locking +the screen (defaults to ‘i3exit lock’) \* system.suspend: specify a +command for suspending (defaults to ‘i3exit suspend’) \* +system.hibernate: specify a command for hibernating (defaults to ‘i3exit +hibernate’) \| \|taskwarrior \|Displays the number of pending tasks in +TaskWarrior.Requires the following library: \* taskwParameters: \* +taskwarrior.taskrc : path to the taskrc file (defaults to ~/.taskrc) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|taskwarrior| \| \|test \|Test module \| \|time \|Displays the current +date and time.Parameters: \* time.format: strftime()-compatible +formatting string \* time.locale: locale to use rather than the system +default + +.. raw:: html + +

+ +.. raw:: html + +

+ +|time| \| \|timetz \|Displays the current date and time.Parameters: \* +time.format: strftime()-compatible formatting string \* time.locale: +locale to use rather than the system default \| \|title \|Displays +focused i3 window title.Requirements: \* i3ipcParameters: \* title.max : +Maximum character length for title before truncating. Defaults to 64. \* +title.placeholder : Placeholder text to be placed if title was +truncated. Defaults to ‘…’. \* title.scroll : Boolean flag for scrolling +title. Defaults to False + +.. raw:: html + +

+ +.. raw:: html + +

+ +|title| \| \|todo \|Displays the number of todo items from a text +fileParameters: \* todo.file: File to read TODOs from (defaults to +~/Documents/todo.txt) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|todo| \| \|traffic \|Displays network IO for interfaces.Parameters: \* +traffic.exclude: Comma-separated list of interface prefixes to exclude +(defaults to ‘lo,virbr,docker,vboxnet,veth’) \* traffic.states: +Comma-separated list of states to show (prefix with ‘^’ to invert - +i.e. ^down -> show all devices that are not in state down) \* +traffic.showname: If set to False, hide network interface name (defaults +to True) \* traffic.format: Format string for download/upload speeds. +Defaults to ‘{:.2f}’ \* traffic.graphlen: Graph lenth in seconds. +Positive even integer. Each char shows 2 seconds. If set, enables +up/down traffic graphs + +.. raw:: html + +

+ +.. raw:: html + +

+ +|traffic| \| \|twmn \|Toggle twmn notifications. \| \|uptime \|Displays +the system uptime. + +.. raw:: html + +

+ +.. raw:: html + +

+ +|uptime| \| \|vault \|Copy passwords from a password store into the +clipboard (currently supports only ‘pass’)Many thanks to +[@bbernhard](https://github.com/bbernhard) for the idea!Parameters: \* +vault.duration: Duration until password is cleared from clipboard +(defaults to 30) \* vault.location: Location of the password store +(defaults to ~/.password-store) \* vault.offx: x-axis offset of popup +menu (defaults to 0) \* vault.offy: y-axis offset of popup menu +(defaults to 0) + +.. raw:: html + +

+ +.. raw:: html + +

+ +|vault| \| \|vpn \|Displays the VPN profile that is currently in +use.Left click opens a popup menu that lists all available VPN profiles +and allows to establisha VPN connection using that +profile.Prerequisites: \* tk python library (usually python-tk or +python3-tk, depending on your distribution) \* nmcli needs to be +installed and configured properly. To quickly test, whether nmcli is +working correctly, type ‘nmcli -g NAME,TYPE,DEVICE con’ which lists all +the connection profiles that are configured. Make sure that your VPN +profile is in that list! e.g: to import a openvpn profile via nmcli: +sudo nmcli connection import type openvpn file + \| \|watson \|Displays the status +of watson (time-tracking tool)Requires the following executable: \* +watson \| \|weather \|Displays the temperature on the current location +based on the ipRequires the following python packages: \* +requestsParameters: \* weather.location: Set location, defaults to +‘auto’ for getting location automatically from a web service If set to a +comma-separated list, left-click and right-click can be used to rotate +the locations. Locations should be city names or city ids. \* +weather.unit: metric (default), kelvin, imperial \* weather.showcity: If +set to true, show location information, otherwise hide it (defaults to +true) \* weather.showminmax: If set to true, show the minimum and +maximum temperature, otherwise hide it (defaults to false) \* +weather.apikey: API key from http://api.openweathermap.org + +.. raw:: html + +

+ +.. raw:: html + +

+ +|weather| \| \|xkcd \|Opens a random xkcd comic in the browser. \| +\|xrandr \|Shows a widget for each connected screen and allows the user +to enable/disable screens.Parameters: \* xrandr.overwrite_i3config: If +set to ‘true’, this module assembles a new i3 config every time a screen +is enabled or disabled by taking the file ‘~/.config/i3/config.template’ +and appending a file ‘~/.config/i3/config.’ for every +screen. \* xrandr.autoupdate: If set to ‘false’, does *not* invoke +xrandr automatically. Instead, the module will only refresh when +displays are enabled or disabled (defaults to true)Requires the +following python module: \* (optional) i3 - if present, the need for +updating the widget list is auto-detectedRequires the following +executable: \* xrandr + +.. raw:: html + +

+ +.. raw:: html + +

+ +|xrandr| \| \|yubikey \|Shows yubikey informationRequires: +https://github.com/Yubico/python-yubicoThe output indicates that a +YubiKey is not connected or it displaysthe corresponding serial number. +\| \|zpool \|Displays info about zpools present on the systemParameters: +\* zpool.list: Comma-separated list of zpools to display info for. If +empty, info for all zpools is displayed. (Default: ’‘) \* zpool.format: +Format string, tags {name}, {used}, {left}, {size}, {percentfree}, +{percentuse}, {status}, {shortstatus}, {fragpercent}, {deduppercent} are +supported. (Default:’{name} {used}/{size} ({percentfree}%)‘) \* +zpool.showio: Show also widgets detailing current read and write I/O +(Default: true) \* zpool.ioformat: Format string for I/O widget, tags +{ops} (operations per seconds) and {band} (bandwidth) are supported. +(Default:’{band}’) \* zpool.warnfree: Warn if free space is below this +percentage (Default: 10) \* zpool.sudo: Use sudo when calling the +``zpool`` binary. (Default: false)Option ``zpool.sudo`` is intended for +Linux users using zfsonlinux older than 0.7.0: In pre-0.7.0releases of +zfsonlinux regular users couldn’t invoke even informative commands such +as\ ``zpool list``. If this option is true, command ``zpool list`` is +invoked with sudo. If this optionis used, the following (or ekvivalent) +must be added to the +``sudoers(5)``:\ ``
\ ALL = (root) NOPASSWD: /usr/bin/zpool list
``\ Be +aware of security implications of doing this! + +.. raw:: html + +

+ +.. raw:: html + +

+ +|zpool| \| + +.. |amixer| image:: ../screenshots/amixer.png +.. |battery| image:: ../screenshots/battery.png +.. |bluetooth| image:: ../screenshots/bluetooth.png +.. |brightness| image:: ../screenshots/brightness.png +.. |caffeine| image:: ../screenshots/caffeine.png +.. |cmus| image:: ../screenshots/cmus.png +.. |cpu| image:: ../screenshots/cpu.png +.. |currency| image:: ../screenshots/currency.png +.. |date| image:: ../screenshots/date.png +.. |datetime| image:: ../screenshots/datetime.png +.. |disk| image:: ../screenshots/disk.png +.. |dnf| image:: ../screenshots/dnf.png +.. |dunst| image:: ../screenshots/dunst.png +.. |getcrypto| image:: ../screenshots/getcrypto.png +.. |git| image:: ../screenshots/git.png +.. |github| image:: ../screenshots/github.png +.. |http_status| image:: ../screenshots/http_status.png +.. |indicator| image:: ../screenshots/indicator.png +.. |kernel| image:: ../screenshots/kernel.png +.. |layout| image:: ../screenshots/layout.png +.. |load| image:: ../screenshots/load.png +.. |memory| image:: ../screenshots/memory.png +.. |mpd| image:: ../screenshots/mpd.png +.. |nic| image:: ../screenshots/nic.png +.. |pacman| image:: ../screenshots/pacman.png +.. |ping| image:: ../screenshots/ping.png +.. |redshift| image:: ../screenshots/redshift.png +.. |sensors| image:: ../screenshots/sensors.png +.. |sensors2| image:: ../screenshots/sensors2.png +.. |shortcut| image:: ../screenshots/shortcut.png +.. |spacer| image:: ../screenshots/spacer.png +.. |spotify| image:: ../screenshots/spotify.png +.. |stock| image:: ../screenshots/stock.png +.. |taskwarrior| image:: ../screenshots/taskwarrior.png +.. |time| image:: ../screenshots/time.png +.. |title| image:: ../screenshots/title.png +.. |todo| image:: ../screenshots/todo.png +.. |traffic| image:: ../screenshots/traffic.png +.. |uptime| image:: ../screenshots/uptime.png +.. |vault| image:: ../screenshots/vault.png +.. |weather| image:: ../screenshots/weather.png +.. |xrandr| image:: ../screenshots/xrandr.png +.. |zpool| image:: ../screenshots/zpool.png diff --git a/doc/other/NOTES.md b/docs/other/NOTES.md similarity index 100% rename from doc/other/NOTES.md rename to docs/other/NOTES.md diff --git a/docs/themes.rst b/docs/themes.rst new file mode 100644 index 0000000..53beb10 --- /dev/null +++ b/docs/themes.rst @@ -0,0 +1,134 @@ +Themes +====== + +Here are some screenshots of various themes: + +.. warning:: Some themes (e.g. all ‘powerline’ themes) require `Font + Awesome `__ and a powerline-compatible font + (`powerline-fonts `__. + +.. note:: If you want to add your own theme, just drop it into + `~/.config/bumblebee-status/themes/` + +Gruvbox Powerline (``-t gruvbox-powerline``) (contributed by +`TheEdgeOfRage `__): + +.. figure:: ../screenshots/themes/powerline-gruvbox.png + :alt: Gruvbox Powerline + + Gruvbox Powerline + +Gruvbox Powerline Light (``-t gruvbox-powerline-light``) (contributed by +`freed00m `__): + +.. figure:: ../screenshots/themes/gruvbox-powerline-light.png + :alt: Gruvbox Powerline Light + + Gruvbox Powerline Light + +Solarized Powerline (``-t solarized-powerline``): + +.. figure:: ../screenshots/themes/powerline-solarized.png + :alt: Solarized Powerline + + Solarized Powerline + +Gruvbox (``-t gruvbox``): + +.. figure:: ../screenshots/themes/gruvbox.png + :alt: Gruvbox + + Gruvbox + +Gruvbox Light (``-t gruvbox-light``) (contributed by +`freed00m `__): + +.. figure:: ../screenshots/themes/gruvbox-light.png + :alt: Gruvbox Light + + Gruvbox Light + +Solarized (``-t solarized``): + +.. figure:: ../screenshots/themes/solarized.png + :alt: Solarized + + Solarized + +Powerline (``-t powerline``): + +.. figure:: ../screenshots/themes/powerline.png + :alt: Powerline + + Powerline + +Greyish Powerline (``-t greyish-powerline``) (contributed by Joshua +Bark): + +.. figure:: ../screenshots/themes/powerline-greyish.png + :alt: Greyish Powerline + + Greyish Powerline + +Iceberg (``-t iceberg``) (contributed by +`whzup `__): + +.. figure:: ../screenshots/themes/iceberg.png + :alt: Iceberg + + Iceberg + +Iceberg Powerline (``-t iceberg-powerline``) (contributed by +`whzup `__): + +.. figure:: ../screenshots/themes/iceberg-powerline.png + :alt: Iceberg Powerline + + Iceberg Powerline + +Iceberg Dark Powerline (``-t iceberg-dark-powerline``) (contributed by +`gkeep `__): + +.. figure:: ../screenshots/themes/iceberg-dark-powerline.png + :alt: Iceberg Dark Powerline + + Iceberg Dark Powerline + +Iceberg Rainbow (``-t iceberg-rainbow``) (contributed by +`whzup `__): + +.. figure:: ../screenshots/themes/iceberg-rainbow.png + :alt: Iceberg Rainbow + + Iceberg Rainbow + +Iceberg Contrast (``-t iceberg-contrast``) (contributed by +`martindoublem `__): + +.. figure:: ../screenshots/themes/iceberg-contrast.png + :alt: Iceberg Contrast + + Iceberg Contrast + +One Dark Powerline (``-t onedark-powerline``) (contributed by +`dillasyx `__): + +.. figure:: ../screenshots/themes/onedark-powerline.png + :alt: One Dark Powerline + + One Dark Powerline + +Dracula Powerline (-t dracula-powerline) (contributed by +`xsteadfastx `__): + +.. figure:: ../screenshots/themes/dracula-powerline.png + :alt: Dracula Powerline + + Dracula Powerline + +Default (nothing or ``-t default``): + +.. figure:: ../screenshots/themes/default.png + :alt: Default + + Default