From 317d96b1769377b72465d8f3527fea5c55fc99bb Mon Sep 17 00:00:00 2001 From: enkore Date: Sat, 6 Jun 2015 00:48:45 +0200 Subject: [PATCH] docs --- docs/configuration.rst | 2 +- docs/formatting.rst | 11 ++++++----- docs/module.rst | 11 +++++------ i3pystatus/core/__init__.py | 13 ++++++++++++- 4 files changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index 966c959..109df38 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -2,7 +2,7 @@ Configuration ============= The configuration file is a normal Python script. The status bar is controlled by a central -status object, which individual *modules* like a :py:mod:`.clock` or a :py:mod:`.battery` +:py:class:`.Status` object, which individual *modules* like a :py:mod:`.clock` or a :py:mod:`.battery` monitor are added to with the ``register`` method. A typical configuration file could look like this (note the additional diff --git a/docs/formatting.rst b/docs/formatting.rst index 6304b7a..8de1777 100644 --- a/docs/formatting.rst +++ b/docs/formatting.rst @@ -15,8 +15,9 @@ decimal dot formatp ------- -Some modules use an extended format string syntax (the mpd module, for example). -Given the format string below the output adapts itself to the available data. +Some modules use an extended format string syntax (the :py:mod:`.mpd` +module, for example). Given the format string below the output adapts +itself to the available data. :: @@ -33,14 +34,14 @@ Inside a group always all format specifiers must evaluate to true (logical and). You can nest groups. The inner group will only become part of the output if both the outer group and the inner group are eligible for output. - .. _TimeWrapper: TimeWrapper ----------- -Some modules that output times use TimeWrapper to format these. TimeWrapper is -a mere extension of the standard formatting method. +Some modules that output times use :py:class:`.TimeWrapper` to format +these. TimeWrapper is a mere extension of the standard formatting +method. The time format that should be used is specified using the format specifier, i.e. with some_time being 3951 seconds a format string like ``{some_time:%h:%m:%s}`` diff --git a/docs/module.rst b/docs/module.rst index 44d5e66..5390383 100644 --- a/docs/module.rst +++ b/docs/module.rst @@ -8,14 +8,13 @@ updates it's info periodically, like checking for a network link or displaying the status of some service, then we have prepared common tools for this which make this even easier: -- Common base classes: :py:class:`i3pystatus.core.modules.Module` for - everything and :py:class:`i3pystatus.core.modules.IntervalModule` - specifically for the aforementioned usecase of updating stuff - periodically. +- Common base classes: :py:class:`.Module` for everything and + :py:class:`.IntervalModule` specifically for the aforementioned + usecase of updating stuff periodically. - Settings (already built into above classes) allow you to easily specify user-modifiable attributes of your class for configuration. - See :py:class:`i3pystatus.core.settings.SettingsBase` for details. + See :py:class:`.SettingsBase` for details. - For modules that require credentials, it is recommended to add a keyring_backend setting to allow users to specify their own backends for retrieving sensitive credentials. @@ -36,7 +35,7 @@ reStructuredText description for your module in the README file. .. seealso:: - :py:class:`i3pystatus.core.settings.SettingsBase` for a detailed description of the settings system + :py:class:`.SettingsBase` for a detailed description of the settings system Handling Dependencies --------------------- diff --git a/i3pystatus/core/__init__.py b/i3pystatus/core/__init__.py index 0b5af1f..67afea8 100644 --- a/i3pystatus/core/__init__.py +++ b/i3pystatus/core/__init__.py @@ -57,7 +57,15 @@ class Status: self.io = io.IOHandler(input_stream) def register(self, module, *args, **kwargs): - """Register a new module.""" + """ + Register a new module. + + :param module: Either a string module name, or a module class, + or a module instance (in which case args and kwargs are + invalid). + :param kwargs: Settings for the module. + :returns: module instance + """ from i3pystatus.text import Text if not module: @@ -81,6 +89,9 @@ class Status: text=configuration_error.message)) def run(self): + """ + Run main loop. + """ if self.click_events: self.command_endpoint.start() for j in io.JSONIO(self.io).read():