storage:util:config: path() now defaults to ~/.config/bugs-everywhere

Add a documentation section discussing the config file, respect
XDG_CONFIG_HOME, and add BE_CONFIG_PATH.

3 files changed, 48 insertions, 2 deletions

diff --git a/doc/config.txt b/doc/config.txt
new file mode 100644
index 0000000..fd274ed
--- /dev/null
+++ b/doc/config.txt
@@ -0,0 +1,34 @@
+*************
+Configuration
+*************
+
+Config file format and location
+===============================
+
+Most of the information that BE needs lives in the bug repository
+itself, but there is user-specific information that does not fit into
+a shared repository.  This per-user configuration information is
+stored in an `INI-style config file`__::
+
+  [default]
+  user = 'John Doe <jdoe@example.com>'
+
+__ configparser_
+
+The config file is located at ``~/.config/bugs-everywhere`` by
+default, but you can override the path by setting environment
+variables (see :py:func:`~libbe.storage.util.config.path` for
+details).
+
+Settings
+========
+
+Currently the only information stored in the configuration file is a
+user ID (see :py:func:`~libbe.ui.util.user.get_user_id`), as shown in
+the example above.  However, many version control systems allow you to
+specify your name and email address, and BE will fall back to the
+VCS-configured values, so you probably don't need to set a BE-specific
+configuration.
+
+
+.. _configparser: http://docs.python.org/library/configparser.html
diff --git a/doc/index.txt b/doc/index.txt
index 7745d0c..f7ba34f 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -24,6 +24,7 @@ Contents:
 
    install
    tutorial
+   config
    email
    http
    distributed_bugtracking
diff --git a/libbe/storage/util/config.py b/libbe/storage/util/config.py
index 771767f..7f1e33c 100644
--- a/libbe/storage/util/config.py
+++ b/libbe/storage/util/config.py
@@ -23,6 +23,7 @@
 
 import ConfigParser
 import codecs
+import os
 import os.path
 
 import libbe
@@ -40,9 +41,19 @@ Initialized with :func:`libbe.util.encoding.get_text_file_encoding`.
 def path():
     """Return the path to the per-user config file.
 
-    Defaults to :file:`~/.bugs_everywhere`.
+    Defaults to :file:`~/.config/bugs-everywhere`, but you can
+    override the directory with ``XDG_CONFIG_HOME`` from the `XDG Base
+    Directory Specification`_.  You can also override the entire path
+    by setting the ``BE_CONFIG_PATH`` environment variable.
+
+    .. _XDG Base Directory Specification:
+      http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html
     """
-    return os.path.expanduser(os.path.join('~','.bugs_everywhere'))
+    default_dir = os.path.join('~', '.config')
+    dirname = os.path.expanduser(
+        os.environ.get('XDG_CONFIG_HOME', default_dir))
+    default = os.path.join(dirname, 'bugs-everywhere')
+    return os.path.expanduser(os.environ.get('BE_CONFIG_PATH', default))
 
 def set_val(name, value, section="DEFAULT", encoding=None):
     """Set a value in the per-user config file.