Update README

README.md

@@ -32,7 +32,119 @@ for it in these places:
     /etc/xdg/i3pystatus.py
     $XDG_CONFIG_DIRS/i3pystatus.py
 
-A sample configuration file is `i3pystatus/__main__.py.dist`
+The config file is just a normal Python module that is executed if you execute
+i3pystatus (it is placed inside the i3pystatus package).
+
+You can also execute your config file instead of i3pystatus, but you need to
+use an absolute import (`from i3pystatus import Status`) and cannot name it
+i3pystatus.py. This is very handy for using different status lines for different
+outputs.
+
+A simple configuration file could look like this (note the additional dependencies
+from network, wireless and pulseaudio in this example):
+
+    # -*- coding: utf-8 -*-
+
+    import subprocess
+
+    from . import Status
+
+    status = Status(standalone=True)
+
+    # Displays clock like this:
+    # Tue 30 Jul 11:59:46 PM KW31
+    #                          ^-- calendar week
+    status.register("clock",
+        format="%a %-d %b %X KW%V",)
+
+    # Shows the average load of the last minute and the last 5 minutes
+    # (the default value for format is used)
+    status.register("load")
+
+    # Shows your CPU temperature, if you have a Intel CPU
+    status.register("temp",
+        format="{temp:.0f}°C",)
+
+    # The battery monitor has many formatting options, see README for details
+
+    # This would look like this, when discharging (or charging)
+    # ↓14.22W 56.15% [77.81%] 2h:41m
+    # And like this if full:
+    # =14.22W 100.0% [91.21%]
+    #
+    # This would also display a desktop notification (via dbus) if the percentage
+    # goes below 5 percent while discharging. The block will also color RED.
+    status.register("battery",
+        format="{status}/{consumption:.2f}W {percentage:.2f}% [{percentage_design:.2f}%] {remaining_hm}",
+        alert=True,
+        alert_percentage=5,
+        status={
+            "DIS": "↓",
+            "CHR": "↑",
+            "FULL": "=",
+        },)
+
+    # This would look like this:
+    # Discharging 6h:51m
+    status.register("battery",
+        format="{status} {remaining_hm}",
+        alert=True,
+        alert_percentage=5,
+        status={
+            "DIS":  "Discharging",
+            "CHR":  "Charging",
+            "FULL": "Bat full",
+        },)
+
+    # Displays whether a DHCP client is running
+    status.register("runwatch",
+        name="DHCP",
+        path="/var/run/dhclient*.pid",)
+
+    # Shows the address and up/down state of eth0. If it is up the address is shown in
+    # green (the default value of color_up) and the CIDR-address is shown
+    # (i.e. 10.10.10.42/24).
+    # If it's down just the interface name (eth0) will be displayed in red
+    # (defaults of format_down and color_down)
+    #
+    # Note: the network module requires PyPI package netifaces-py3
+    status.register("network",
+        interface="eth0",
+        format_up="{v4cidr}",)
+
+    # Has all the options of the normal network and adds some wireless specific things
+    # like quality and network names.
+    #
+    # Note: requires both netifaces-py3 and basiciw
+    status.register("wireless",
+        interface="wlan0",
+        format_up="{essid} {quality:03.0f}%",)
+
+    # Shows disk usage of /
+    # Format:
+    # 42/128G [86G]
+    status.register("disk",
+        path="/",
+        format="{used}/{total}G [{avail}G]",)
+
+    # Shows pulseaudio default sink volume
+    #
+    # Note: requires libpulseaudio from PyPI
+    status.register("pulseaudio",
+        format="♪{volume}",)
+
+    # Shows mpd status
+    # Format:
+    # Cloud connected▶Reroute to Remain
+    status.register("mpd",
+        format="{title}{status}{album}",
+        status={
+            "pause": "▷",
+            "play": "▶",
+            "stop": "◾",
+        },)
+
+    status.run()
 
 Also change your i3wm config to the following:
 
@@ -112,7 +224,7 @@ __Settings:__
 * `alert_format_body` —  (default: `Battery {battery_ident} has only {percentage:.2f}% ({remaining_hm}) remaining!`)
 * `alert_percentage` —  (default: `10`)
 * `path` —  (default: `None`)
-* `status` — A dictionary mapping ('DIS', 'CHR', 'FULL') to alternative names (default: `{'DIS': 'DIS', 'CHR': 'CHR', 'FULL': 'FULL'}`)
+* `status` — A dictionary mapping ('DIS', 'CHR', 'FULL') to alternative names (default: `{'CHR': 'CHR', 'FULL': 'FULL', 'DIS': 'DIS'}`)
 
 
 
@@ -296,7 +408,7 @@ __Settings:__
 * `host` —  (default: `localhost`)
 * `port` — MPD port (default: `6600`)
 * `format` —  (default: `{title} {status}`)
-* `status` — Dictionary mapping pause, play and stop to output (default: `{'stop': '◾', 'pause': '▷', 'play': '▶'}`)
+* `status` — Dictionary mapping pause, play and stop to output (default: `{'play': '▶', 'pause': '▷', 'stop': '◾'}`)
 
 
 
@@ -475,9 +587,10 @@ use IntervalModule, which just calls a function repeatedly in a specified interv
 The output attribute should be set to a dictionary which represents your modules output,
 the protocol is documented [here](http://i3wm.org/docs/i3bar-protocol.html).
 
-Please add an example for how to configure it to `__main__.py.dist`. It should be
-a python class that can be registered with the `I3statusHandler` class. Also don't
-forget to add yourself to the LICENSE file.
-
 **Patches and pull requests are very welcome :-)**
 
+### The README
+
+The README.md file is generated from the README.tpl.md file; only edit the latter
+and run `python -m i3pystatus.mkdocs`.
+

README.tpl.md

@@ -32,7 +32,119 @@ for it in these places:
     /etc/xdg/i3pystatus.py
     $XDG_CONFIG_DIRS/i3pystatus.py
 
-A sample configuration file is `i3pystatus/__main__.py.dist`
+The config file is just a normal Python module that is executed if you execute
+i3pystatus (it is placed inside the i3pystatus package).
+
+You can also execute your config file instead of i3pystatus, but you need to
+use an absolute import (`from i3pystatus import Status`) and cannot name it
+i3pystatus.py. This is very handy for using different status lines for different
+outputs.
+
+A simple configuration file could look like this (note the additional dependencies
+from network, wireless and pulseaudio in this example):
+
+    # -*- coding: utf-8 -*-
+
+    import subprocess
+
+    from . import Status
+
+    status = Status(standalone=True)
+
+    # Displays clock like this:
+    # Tue 30 Jul 11:59:46 PM KW31
+    #                          ^-- calendar week
+    status.register("clock",
+        format="%a %-d %b %X KW%V",)
+
+    # Shows the average load of the last minute and the last 5 minutes
+    # (the default value for format is used)
+    status.register("load")
+
+    # Shows your CPU temperature, if you have a Intel CPU
+    status.register("temp",
+        format="{temp:.0f}°C",)
+
+    # The battery monitor has many formatting options, see README for details
+
+    # This would look like this, when discharging (or charging)
+    # ↓14.22W 56.15% [77.81%] 2h:41m
+    # And like this if full:
+    # =14.22W 100.0% [91.21%]
+    #
+    # This would also display a desktop notification (via dbus) if the percentage
+    # goes below 5 percent while discharging. The block will also color RED.
+    status.register("battery",
+        format="{status}/{consumption:.2f}W {percentage:.2f}% [{percentage_design:.2f}%] {remaining_hm}",
+        alert=True,
+        alert_percentage=5,
+        status={
+            "DIS": "↓",
+            "CHR": "↑",
+            "FULL": "=",
+        },)
+
+    # This would look like this:
+    # Discharging 6h:51m
+    status.register("battery",
+        format="{status} {remaining_hm}",
+        alert=True,
+        alert_percentage=5,
+        status={
+            "DIS":  "Discharging",
+            "CHR":  "Charging",
+            "FULL": "Bat full",
+        },)
+
+    # Displays whether a DHCP client is running
+    status.register("runwatch",
+        name="DHCP",
+        path="/var/run/dhclient*.pid",)
+
+    # Shows the address and up/down state of eth0. If it is up the address is shown in
+    # green (the default value of color_up) and the CIDR-address is shown
+    # (i.e. 10.10.10.42/24).
+    # If it's down just the interface name (eth0) will be displayed in red
+    # (defaults of format_down and color_down)
+    #
+    # Note: the network module requires PyPI package netifaces-py3
+    status.register("network",
+        interface="eth0",
+        format_up="{v4cidr}",)
+
+    # Has all the options of the normal network and adds some wireless specific things
+    # like quality and network names.
+    #
+    # Note: requires both netifaces-py3 and basiciw
+    status.register("wireless",
+        interface="wlan0",
+        format_up="{essid} {quality:03.0f}%",)
+
+    # Shows disk usage of /
+    # Format:
+    # 42/128G [86G]
+    status.register("disk",
+        path="/",
+        format="{used}/{total}G [{avail}G]",)
+
+    # Shows pulseaudio default sink volume
+    #
+    # Note: requires libpulseaudio from PyPI
+    status.register("pulseaudio",
+        format="♪{volume}",)
+
+    # Shows mpd status
+    # Format:
+    # Cloud connected▶Reroute to Remain
+    status.register("mpd",
+        format="{title}{status}{album}",
+        status={
+            "pause": "▷",
+            "play": "▶",
+            "stop": "◾",
+        },)
+
+    status.run()
 
 Also change your i3wm config to the following:
 
@@ -58,8 +170,9 @@ use IntervalModule, which just calls a function repeatedly in a specified interv
 The output attribute should be set to a dictionary which represents your modules output,
 the protocol is documented [here](http://i3wm.org/docs/i3bar-protocol.html).
 
-Please add an example for how to configure it to `__main__.py.dist`. It should be
-a python class that can be registered with the `I3statusHandler` class. Also don't
-forget to add yourself to the LICENSE file.
-
 **Patches and pull requests are very welcome :-)**
+
+### The README
+
+The README.md file is generated from the README.tpl.md file; only edit the latter
+and run `python -m i3pystatus.mkdocs`.