add XDG_CONFIG_HOME for py3status, organize paths

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 <path to config
 file>`` in your i3 configuration file.

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!

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:
 ::

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 <path to custom
+modules directory>`` 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.
 

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 = []

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:

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))