[doc] Add README.rst
This commit is contained in:
Tobias Witek
parent
8ac9cdb913
commit
2a84346221
1 changed files with 430 additions and 0 deletions
430
README.rst
Normal file
430
README.rst
Normal file
|
|
@ -0,0 +1,430 @@
|
|||
bumblebee-status
|
||||
================
|
||||
|
||||
|Build Status| |Code Climate| |Test Coverage| |Issue Count|
|
||||
|
||||
**Many, many thanks to all contributors! As of now, 54 of the modules
|
||||
are from various contributors (!), and only 19 from myself.**
|
||||
|
||||
.. figure:: ./Modules.md
|
||||
:alt: List of modules
|
||||
|
||||
List of modules
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/powerline-solarized.png
|
||||
:alt: Solarized Powerline
|
||||
|
||||
Solarized Powerline
|
||||
|
||||
bumblebee-status is a modular, theme-able status line generator for the
|
||||
`i3 window manager <https://i3wm.org/>`__.
|
||||
|
||||
Focus is on: \* Ease of use (no configuration files!) \* Theme support
|
||||
\* Extensibility (of course…)
|
||||
|
||||
One thing I like in particular: You can use the mouse wheel up/down to
|
||||
switch workspaces forward and back everywhere throughout the bar (unless
|
||||
you have mapped the mouse wheel buttons to another action for a widget,
|
||||
in which case this doesn’t work while hovering that particular widget).
|
||||
|
||||
I hope you like it and 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: 2.7, 3.3, 3.4, 3.5, 3.6
|
||||
|
||||
Supported FontAwesome version: 4 (free version of 5 doesn’t include some
|
||||
of the icons)
|
||||
|
||||
Explicitly unsupported Python versions: 3.2 (missing unicode literals)
|
||||
|
||||
:information_source: 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.
|
||||
|
||||
::
|
||||
|
||||
# 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
|
||||
|
||||
Example usage:
|
||||
|
||||
::
|
||||
|
||||
bar {
|
||||
status_command <path>/bumblebee-status -m cpu memory battery time pasink pasource -p time.format="%H:%M" -t solarized
|
||||
}
|
||||
|
||||
Documentation
|
||||
=============
|
||||
|
||||
See `the
|
||||
wiki <https://github.com/tobi-wan-kenobi/bumblebee-status/wiki>`__ for
|
||||
documentation.
|
||||
|
||||
See
|
||||
`FAQ <https://github.com/tobi-wan-kenobi/bumblebee-status/wiki/FAQ>`__
|
||||
for, well, FAQs.
|
||||
|
||||
Other resources:
|
||||
|
||||
- A list of `available
|
||||
modules <https://github.com/tobi-wan-kenobi/bumblebee-status/wiki/Available-Modules>`__
|
||||
- `How to write a
|
||||
theme <https://github.com/tobi-wan-kenobi/bumblebee-status/wiki/How-to-write-a-theme>`__
|
||||
- `How to write a
|
||||
module <https://github.com/tobi-wan-kenobi/bumblebee-status/wiki/How-to-write-a-module>`__
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
::
|
||||
|
||||
$ git clone git://github.com/tobi-wan-kenobi/bumblebee-status
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
`Available
|
||||
modules <https://github.com/tobi-wan-kenobi/bumblebee-status/wiki/Available-Modules>`__
|
||||
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:
|
||||
|
||||
::
|
||||
|
||||
bar {
|
||||
status_command <path to bumblebee-status/bumblebee-status> \
|
||||
-m <list of modules> \
|
||||
-p <list of module parameters> \
|
||||
-t <theme>
|
||||
}
|
||||
|
||||
You can retrieve a list of modules (and their parameters) and themes by
|
||||
entering:
|
||||
|
||||
::
|
||||
|
||||
$ cd bumblebee-status
|
||||
$ ./bumblebee-status -l themes
|
||||
$ ./bumblebee-status -l modules
|
||||
|
||||
Any parameter you can specify with ``-p <name>=<value>``, you can
|
||||
alternatively specify in ``~/.bumblebee-status.conf`` or
|
||||
``~/.config/bumblebee-status.conf``. This parameters act as a
|
||||
**fallback**, so values specified with ``-p`` have priority.
|
||||
|
||||
Parameters can also be used to override theme settings, such as:
|
||||
|
||||
::
|
||||
|
||||
$ ./bumblebee-status -p <module>.theme.<theme field>=<value>
|
||||
# for example, to get a spacer with a red background:
|
||||
$ ./bumblebee-status -m spacer -p spacer.theme.bg=#ff0000
|
||||
|
||||
Configuration files have a format like this:
|
||||
|
||||
::
|
||||
|
||||
$ cat ~/.bumblebee-status.conf
|
||||
[module-parameters]
|
||||
<key> = <value>
|
||||
|
||||
For example:
|
||||
|
||||
::
|
||||
|
||||
$ cat ~/.bumblebee-status.conf
|
||||
[module-parameters]
|
||||
github.token=abcdefabcdef12345
|
||||
|
||||
To change the update interval, use:
|
||||
|
||||
::
|
||||
|
||||
$ ./bumblebee-status -m <list of modules> -p interval=<interval in seconds>
|
||||
|
||||
As a simple example, this is what my i3 configuration looks like:
|
||||
|
||||
::
|
||||
|
||||
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!
|
||||
|
||||
Events
|
||||
------
|
||||
|
||||
By default, the following events are handled:
|
||||
|
||||
- Mouse-Wheel on any module moves to the next/previous i3 workspace
|
||||
- Left-click on the “disk” module opens the specified path in nautilus
|
||||
- Left-click on either “memory” or “cpu” opens gnome-system-monitor
|
||||
- Left-click on a “pulseaudio” (or pasource/pasink) module toggles the
|
||||
mute state
|
||||
- Right-click on a “pulseaudio” module opens pavucontrol
|
||||
- Mouse-Wheel up/down on a “pulseaudio” module raises/lowers the volume
|
||||
|
||||
By default, the Mouse-Wheel wraps for the current output. You can
|
||||
disable this behavior by providing the parameter
|
||||
``engine.workspacewrap=false`` (starting with version 1.4.5). Also, you
|
||||
can completely disable output switching by using
|
||||
``engine.workspacewheel=false``.
|
||||
|
||||
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}"``
|
||||
|
||||
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 <list of modules>
|
||||
|
||||
This will create a file called ``~/bumblebee-status-debug.log`` by
|
||||
default. The file name can be changed by using the ``-f`` or
|
||||
``--logfile`` option.
|
||||
|
||||
Advanced Usage
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
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``).
|
||||
|
||||
Required Modules
|
||||
================
|
||||
|
||||
Modules and commandline utilities are only required for modules, the
|
||||
core itself has no external dependencies at all.
|
||||
|
||||
- psutil (for the modules ‘cpu’, ‘memory’, ‘traffic’)
|
||||
- netifaces (for the modules ‘nic’, ‘traffic’)
|
||||
- requests (for the modules ‘weather’, ‘github’, ‘getcrypto’, ‘stock’,
|
||||
‘currency’, ‘sun’)
|
||||
- power (for the module ‘battery’)
|
||||
- dbus (for the module ‘spotify’, ‘deezer’)
|
||||
- i3ipc (for the module ‘title’)
|
||||
- pacman-contrib (for module ‘arch-update’)
|
||||
- docker (for the module ‘docker_ps’)
|
||||
- pytz (for the module ‘datetimetz’)
|
||||
- localtz (for the module ‘datetimetz’)
|
||||
- suntime (for the module ‘sun’)
|
||||
- feedparser (for the module ‘rss’)
|
||||
|
||||
Required commandline utilities
|
||||
==============================
|
||||
|
||||
- xset (for the module ‘caffeine’)
|
||||
- notify-send (for the module ‘caffeine’)
|
||||
- cmus-remote (for the module ‘cmus’)
|
||||
- dnf (for the module ‘dnf’)
|
||||
- gpmdp-remote (for the module ‘gpmdp’)
|
||||
- setxkbmap (for the module ‘layout’)
|
||||
- fakeroot (for the module ‘pacman’)
|
||||
- pacman (for the module ‘pacman’)
|
||||
- pactl (for the module ‘pulseaudio’)
|
||||
- ping (for the module ‘ping’)
|
||||
- redshift (for the module ‘redshift’)
|
||||
- xrandr (for the module ‘xrandr’)
|
||||
- mpc (for the module ‘mpd’)
|
||||
- bluez / blueman (for module ‘bluetooth’)
|
||||
- dbus-send (for module ‘bluetooth’)
|
||||
- nvidia-smi (for module ‘nvidiagpu’)
|
||||
- sensors (for module ‘sensors’, as fallback)
|
||||
- zpool (for module ‘zpool’)
|
||||
- progress (for module ‘progress’)
|
||||
- i3exit (for module ‘system’)
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
Here are some screenshots for all themes that currently exist:
|
||||
|
||||
:exclamation: Some themes (all ‘Powerline’ themes) require `Font
|
||||
Awesome <http://fontawesome.io/>`__ and a powerline-compatible font
|
||||
(`powerline-fonts <https://github.com/powerline/fonts>`__, for example)
|
||||
to display all icons correctly.
|
||||
|
||||
: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)):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/powerline-gruvbox.png
|
||||
:alt: Gruvbox Powerline
|
||||
|
||||
Gruvbox Powerline
|
||||
|
||||
Gruvbox Powerline Light (``-t gruvbox-powerline-light``) (contributed by
|
||||
`freed00m <https://github.com/freed00m>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/gruvbox-powerline-light.png
|
||||
:alt: Gruvbox Powerline Light
|
||||
|
||||
Gruvbox Powerline Light
|
||||
|
||||
Solarized Powerline (``-t solarized-powerline``):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/powerline-solarized.png
|
||||
:alt: Solarized Powerline
|
||||
|
||||
Solarized Powerline
|
||||
|
||||
Gruvbox (``-t gruvbox``):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/gruvbox.png
|
||||
:alt: Gruvbox
|
||||
|
||||
Gruvbox
|
||||
|
||||
Gruvbox Light (``-t gruvbox-light``) (contributed by
|
||||
`freed00m <https://github.com/freed00m>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/gruvbox-light.png
|
||||
:alt: Gruvbox Light
|
||||
|
||||
Gruvbox Light
|
||||
|
||||
Solarized (``-t solarized``):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/solarized.png
|
||||
:alt: Solarized
|
||||
|
||||
Solarized
|
||||
|
||||
Powerline (``-t powerline``):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/powerline.png
|
||||
:alt: Powerline
|
||||
|
||||
Powerline
|
||||
|
||||
Greyish Powerline (``-t greyish-powerline``) (contributed by Joshua
|
||||
Bark):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/powerline-greyish.png
|
||||
:alt: Greyish Powerline
|
||||
|
||||
Greyish Powerline
|
||||
|
||||
Iceberg (``-t iceberg``) (contributed by
|
||||
`whzup <https://github.com/whzup>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/iceberg.png
|
||||
:alt: Iceberg
|
||||
|
||||
Iceberg
|
||||
|
||||
Iceberg Powerline (``-t iceberg-powerline``) (contributed by
|
||||
`whzup <https://github.com/whzup>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/iceberg-powerline.png
|
||||
:alt: Iceberg Powerline
|
||||
|
||||
Iceberg Powerline
|
||||
|
||||
Iceberg Dark Powerline (``-t iceberg-dark-powerline``) (contributed by
|
||||
`gkeep <https://github.com/gkeep>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/iceberg-dark-powerline.png
|
||||
:alt: Iceberg Dark Powerline
|
||||
|
||||
Iceberg Dark Powerline
|
||||
|
||||
Iceberg Rainbow (``-t iceberg-rainbow``) (contributed by
|
||||
`whzup <https://github.com/whzup>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/iceberg-rainbow.png
|
||||
:alt: Iceberg Rainbow
|
||||
|
||||
Iceberg Rainbow
|
||||
|
||||
One Dark Powerline (``-t onedark-powerline``) (contributed by
|
||||
`dillasyx <https://github.com/dillasyx>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/onedark-powerline.png
|
||||
:alt: One Dark Powerline
|
||||
|
||||
One Dark Powerline
|
||||
|
||||
Dracula Powerline (-t dracula-powerline) (contributed by
|
||||
`xsteadfastx <https://github.com/xsteadfastx>`__):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/dracula-powerline.png
|
||||
:alt: Dracula Powerline
|
||||
|
||||
Dracula Powerline
|
||||
|
||||
Default (nothing or ``-t default``):
|
||||
|
||||
.. figure:: https://github.com/tobi-wan-kenobi/bumblebee-status/blob/master/screenshots/themes/default.png
|
||||
:alt: Default
|
||||
|
||||
Default
|
||||
|
||||
.. |Build Status| image:: https://travis-ci.org/tobi-wan-kenobi/bumblebee-status.svg?branch=master
|
||||
:target: https://travis-ci.org/tobi-wan-kenobi/bumblebee-status
|
||||
.. |Code Climate| image:: https://codeclimate.com/github/tobi-wan-kenobi/bumblebee-status/badges/gpa.svg
|
||||
:target: https://codeclimate.com/github/tobi-wan-kenobi/bumblebee-status
|
||||
.. |Test Coverage| image:: https://codeclimate.com/github/tobi-wan-kenobi/bumblebee-status/badges/coverage.svg
|
||||
:target: https://codeclimate.com/github/tobi-wan-kenobi/bumblebee-status/coverage
|
||||
.. |Issue Count| image:: https://codeclimate.com/github/tobi-wan-kenobi/bumblebee-status/badges/issue_count.svg
|
||||
:target: https://codeclimate.com/github/tobi-wan-kenobi/bumblebee-status
|
||||
.. |Font Awesome| image:: https://fontawesome.com/
|
||||
Loading…
Reference in a new issue