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.

2 files changed, 35 insertions, 0 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