diff --git a/doc/configuration.rst b/doc/configuration.rst index 9b8c0d49cd..61b46dc319 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -1,20 +1,32 @@ -.. _using_modules: +.. _configuration: -Using modules +Configuration ============= py3status comes with a large range of :ref:`modules`. -Modules in py3status are configured using your usual ``i3status.conf``. -py3status tries to find the config in the following locations: +Modules in py3status are configured using your usual ``i3status.conf`` or your +own ``py3status.conf`` which follows the exact same format. -- ``~/.i3/i3status.conf`` +py3status will try to find its configuration file in the following locations: + +- ``~/.config/py3status/config`` +- ``~/.config/i3status/config`` +- ``~/.config/i3/i3status.conf`` - ``~/.i3status.conf`` +- ``~/.i3/i3status.conf`` +- ``/etc/xdg/i3status/config`` - ``/etc/i3status.conf`` -- ``XDG_CONFIG_HOME/.config/i3status/config`` -- ``~/.config/i3status/config`` + +which if you are used to XDG_CONFIG paths relates to: + +- ``XDG_CONFIG_HOME/py3status/config`` +- ``XDG_CONFIG_HOME/i3status/config`` +- ``XDG_CONFIG_HOME/i3/i3status.conf`` +- ``~/.i3status.conf`` +- ``~/.i3/i3status.conf`` - ``XDG_CONFIG_DIRS/i3status/config`` -- ``/etc/xdg/i3status/config`` +- ``/etc/i3status.conf`` You can also specify the config location using ``py3status -c `` in your i3 configuration file. diff --git a/doc/intro.rst b/doc/intro.rst index 05fef219b8..e22ea031e4 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -71,12 +71,12 @@ Installation |**Void Linux** |``$ xbps-install -S py3status``| | +-------------------+-------------------------------+-------------------------------------+ |**NixOS** |``$ nix-env -i`` |Not a global install. See below. | -| | ``python3.6-py3status`` | | +| |``python3.6-py3status`` | | +-------------------+-------------------------------+-------------------------------------+ -Debian/Ubuntu -^^^^^^^^^^^^^ +Note on Debian/Ubuntu +^^^^^^^^^^^^^^^^^^^^^ .. note:: @@ -85,8 +85,8 @@ Debian/Ubuntu python package) instead of directly calling pip. -NixOS -^^^^^ +Note on NixOS +^^^^^^^^^^^^^ To have it globally persistent add to your NixOS configuration file py3status as a Python 3 package with @@ -148,7 +148,7 @@ Usually you have your own i3status configuration, just point to it: .. code-block:: shell - status_command py3status -c ~/.i3/i3status.conf + status_command py3status -c ~/.config/i3status/config Available modules ^^^^^^^^^^^^^^^^^ @@ -215,10 +215,3 @@ Note that this will also send a SIGUSR1 signal to i3status. Since version 3.6 py3status can be controlled via the :ref:`py3-cmd` which is **recommended**. - - -Contributing ------------- - -We value very much any kind of feedback/contribution, see :ref:`contributing` to -read more about how to help! diff --git a/doc/modules.rst b/doc/modules.rst index a6eaf36c8d..5ed629e48a 100644 --- a/doc/modules.rst +++ b/doc/modules.rst @@ -3,7 +3,7 @@ Modules ======= -py3status comes with a large selection of modules ready to use. For information on their configuration see :ref:`using_modules`. +py3status comes with a large selection of modules ready to use. For information on their configuration see :ref:`configuration`. You can also get a list with short descriptions of all available modules by using the CLI: :: diff --git a/doc/writing_modules.rst b/doc/writing_modules.rst index bd3667b165..3e43162707 100644 --- a/doc/writing_modules.rst +++ b/doc/writing_modules.rst @@ -7,11 +7,31 @@ Writing custom py3status modules Writing custom modules for py3status is easy. This guide will teach you how. -Let's start by looking at a simple example. +Importing custom modules +------------------------ + +py3status will try to find custom modules in the following locations: + +- ``~/.config/py3status/modules`` +- ``~/.config/i3status/py3status`` +- ``~/.config/i3/py3status`` +- ``~/.i3/py3status`` + +which if you are used to XDG_CONFIG paths relates to: + +- ``XDG_CONFIG_HOME/py3status/modules`` +- ``XDG_CONFIG_HOME/i3status/py3status`` +- ``XDG_CONFIG_HOME/i3/py3status`` +- ``~/.i3/py3status`` + +You can also specify the modules location using ``py3status -i `` in your i3 configuration file. Example 1: The basics - Hello World! ------------------------------------ +Now let's start by looking at a simple example. + Here we start with the most basic module that just outputs a static string to the status bar. diff --git a/py3status/argparsers.py b/py3status/argparsers.py index 41445d10f4..1d5d61feea 100644 --- a/py3status/argparsers.py +++ b/py3status/argparsers.py @@ -35,10 +35,11 @@ def parse_cli_args(): # i3status config file default detection # respect i3status' file detection order wrt issue #43 i3status_config_file_candidates = [ - "{}/.i3status.conf".format(home_path), + "{}/py3status/config".format(xdg_home_path), "{}/i3status/config".format(xdg_home_path), - "{}/.config/i3/i3status.conf".format(home_path), - "{}/.i3/i3status.conf".format(home_path), + "{}/i3/i3status.conf".format(xdg_home_path), # custom + "{}/.i3status.conf".format(home_path), + "{}/.i3/i3status.conf".format(home_path), # custom "{}/i3status/config".format(xdg_dirs_path), "/etc/i3status.conf", ] @@ -200,10 +201,10 @@ def _format_action_invocation(self, action): # make include path to search for user modules if None if not options.include_paths: options.include_paths = [ - "{}/.i3/py3status".format(home_path), - "{}/.config/i3/py3status".format(home_path), + "{}/py3status/modules".format(xdg_home_path), "{}/i3status/py3status".format(xdg_home_path), "{}/i3/py3status".format(xdg_home_path), + "{}/.i3/py3status".format(home_path), ] include_paths = [] diff --git a/py3status/command.py b/py3status/command.py index d5b449c1c6..a9e4c4586b 100644 --- a/py3status/command.py +++ b/py3status/command.py @@ -465,10 +465,10 @@ def parse_list_or_docstring(options, sps): home_path = os.path.expanduser("~") xdg_home_path = os.environ.get("XDG_CONFIG_HOME", "{}/.config".format(home_path)) options.include_paths = [ - "{}/.i3/py3status/".format(home_path), - "{}/.config/i3/py3status/".format(home_path), + "{}/py3status/modules".format(xdg_home_path), "{}/i3status/py3status".format(xdg_home_path), "{}/i3/py3status".format(xdg_home_path), + "{}/.i3/py3status".format(home_path), ] include_paths = [] for path in options.include_paths: diff --git a/py3status/core.py b/py3status/core.py index 983f399544..2c48f21b0c 100644 --- a/py3status/core.py +++ b/py3status/core.py @@ -538,6 +538,7 @@ def setup(self): # read i3status.conf config_path = self.config["i3status_config_path"] + self.log("config file: {}".format(self.config["i3status_config_path"])) self.config["py3_config"] = process_config(config_path, self) # setup i3status thread @@ -600,6 +601,7 @@ def setup(self): self.py3_modules = self.config["py3_config"]["py3_modules"] # get a dict of all user provided modules + self.log("modules include paths: {}".format(self.config["include_paths"])) user_modules = self.get_user_configured_modules() if self.config["debug"]: self.log("user_modules={}".format(user_modules))