[doc] Update list of modules to produce RST output

Also, adapt some module docstrings to conform with RST

core/config.py

@@ -50,9 +50,9 @@ class print_usage(argparse.Action):
             self._args = namespace
             self._format = "plain"
             self.print_modules()
-        elif value == "modules-markdown":
+        elif value == "modules-rst":
             self._args = namespace
-            self._format = "markdown"
+            self._format = "rst"
             self.print_modules()
         elif value == "themes":
             self.print_themes()
@@ -62,14 +62,12 @@ class print_usage(argparse.Action):
         print(", ".join(core.theme.themes()))
 
     def print_modules(self):
-        if self._format == "markdown":
-            print("# Table of modules")
-            print("|Name |Description |")
-            print("|-----|------------|")
-
         basepath = os.path.abspath(
             os.path.join(os.path.dirname(os.path.realpath(__file__)), "..")
         )
+        if self._format == "rst":
+            print("List of modules\n===============")
+
         for m in all_modules():
             try:
                 filename = os.path.join(basepath, "modules", "core", "{}.py".format(m))
@@ -89,19 +87,13 @@ class print_usage(argparse.Action):
                 if not doc:
                     log.warning("failed to find docstring for {}".format(m))
                     continue
-                if self._format == "markdown":
+                if self._format == "rst":
-                    doc = doc.replace("<", "\<")
+                    print("\n{}\n{}\n".format(m, "-" * len(m)))
-                    doc = doc.replace(">", "\>")
-                    doc = doc.replace("\n", "<br />")
-
                     if os.path.exists(
                         os.path.join(basepath, "screenshots", "{}.png".format(m))
                     ):
-                        doc = "{}<p /><p />![{}](../screenshots/{}.png)".format(
+                        doc = "{}\n\n.. image:: ../screenshots/{}.png".format(doc, m)
-                            doc, m, m
+                    print(doc)
-                        )
-
-                    print("|{} |{} |".format(m, doc))
                 else:
                     print(
                         textwrap.fill(
@@ -173,7 +165,7 @@ class Config(util.store.Store):
         parser.add_argument(
             "-l",
             "--list",
-            choices=["modules", "themes", "modules-markdown"],
+            choices=["modules", "themes", "modules-rst"],
             help="Display a list of available themes or available modules, along with their parameters",
             action=print_usage,
         )

docs/conf.py

@@ -23,7 +23,8 @@ author = "tobi-wan-kenobi"
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('..'))
+
+sys.path.insert(0, os.path.abspath(".."))
 
 # -- General configuration ---------------------------------------------------
 

modules/contrib/apt.py

@@ -2,6 +2,7 @@
 
 """Displays APT package update information (<to upgrade>/<to remove >)
 Requires the following packages:
+
     * aptitude
 
 """

modules/contrib/cpu2.py

@@ -15,18 +15,19 @@ Requirements:
 
 Parameters:
     * cpu2.layout: Space-separated list of widgets to add.
+
       Possible widgets are:
-        * cpu2.maxfreq
+         * cpu2.maxfreq
-        * cpu2.cpuload
+         * cpu2.cpuload
-        * cpu2.coresload
+         * cpu2.coresload
-        * cpu2.temp
+         * cpu2.temp
-        * cpu2.fanspeed
+         * cpu2.fanspeed
     * cpu2.colored: 1 for colored per core load graph, 0 for mono (default)
-                    if this is set to 1, use --markup=pango
+      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
+      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
+      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.

modules/contrib/deadbeef.py

@@ -9,25 +9,26 @@ Requires the following library:
     * subprocess
 Parameters:
     * deadbeef.format:    Format string (defaults to '{artist} - {title}')
-                          Available values are: {artist}, {title}, {album}, {length},
+      Available values are: {artist}, {title}, {album}, {length},
-                                                {trackno}, {year}, {comment},
+      {trackno}, {year}, {comment},
-                                                {copyright}, {time}
+      {copyright}, {time}
-                          This is deprecated, but much simpler.
+      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
+      These can be much more sophisticated than the standard
-                          format strings. This is off by default, but specifying
+      format strings. This is off by default, but specifying
-                          any tf_format will enable it. If both deadbeef.format
+      any tf_format will enable it. If both deadbeef.format
-                          and deadbeef.tf_format are specified, deadbeef.tf_format
+      and deadbeef.tf_format are specified, deadbeef.tf_format
-                          takes priority.
+      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
+      string should be displayed even if no song is paused or
-                          playing. This could be useful if you want to implement
+      playing. This could be useful if you want to implement
-                          your own stop strings with the built in logic. Any non-
+      your own stop strings with the built in logic. Any non-
-                          null value will enable this (by default the module will
+      null value will enable this (by default the module will
-                          hide itself when the player is stopped).
+      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
 

modules/contrib/deezer.py

@@ -1,14 +1,17 @@
 # pylint: disable=C0111,R0903
 
 """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}
+      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
 """

modules/contrib/libvirtvms.py

@@ -1,4 +1,5 @@
 """Displays count of running libvirt VMs.
+
 Required the following python packages:
         * libvirt
 """

modules/contrib/mpd.py

@@ -8,34 +8,37 @@ Requires the following executable:
 
 Parameters:
     * mpd.format: Format string for the song information.
+
       Supported tags (see `man mpc` for additional information)
-        * {name}
+         * {name}
-        * {artist}
+         * {artist}
-        * {album}
+         * {album}
-        * {albumartist}
+         * {albumartist}
-        * {comment}
+         * {comment}
-        * {composer}
+         * {composer}
-        * {date}
+         * {date}
-        * {originaldate}
+         * {originaldate}
-        * {disc}
+         * {disc}
-        * {genre}
+         * {genre}
-        * {performer}
+         * {performer}
-        * {title}
+         * {title}
-        * {track}
+         * {track}
-        * {time}
+         * {time}
-        * {file}
+         * {file}
-        * {id}
+         * {id}
-        * {prio}
+         * {prio}
-        * {mtime}
+         * {mtime}
-        * {mdate}
+         * {mdate}
+
       Additional tags:
-        * {position} - position of currently playing song
+         * {position} - position of currently playing song
-                       not to be confused with %position% mpc tag
+           not to be confused with %position% mpc tag
-        * {duration} - duration of currently playing song
+         * {duration} - duration of currently playing song
-        * {file1} - song file name without path prefix
+         * {file1} - song file name without path prefix
-                    if {file} = '/foo/bar.baz', then {file1} = 'bar.baz'
+           if {file} = '/foo/bar.baz', then {file1} = 'bar.baz'
-        * {file2} - song file name without path prefix and extension suffix
+         * {file2} - song file name without path prefix and extension suffix
-                    if {file} = '/foo/bar.baz', then {file2} = 'bar'
+           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.
 """

modules/contrib/pihole.py

@@ -1,6 +1,7 @@
 # pylint: disable=C0111,R0903
 
 """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)

modules/contrib/sensors.py

@@ -6,8 +6,8 @@
 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. <key1>/<key2>/.../<value>), for example, path could
+      of 'sensors -j' (i.e. <key1>/<key2>/.../<value>), for example, path could
-                    be: 'coretemp-isa-00000/Core 0/temp1_input' (defaults to 'false')
+      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).

modules/contrib/spotify.py

@@ -1,14 +1,17 @@
 # pylint: disable=C0111,R0903
 
 """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}
+      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
 """

modules/contrib/system.py

@@ -6,6 +6,7 @@
 adds the possibility to
 	* shutdown
 	* reboot
+
 the system.
 	
 Per default a confirmation dialog is shown before the actual action is performed.

modules/core/cmus.py

@@ -7,12 +7,13 @@ Requires the following executable:
 
 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'
+          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'
+          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.