From 0fcf492327020fd82f2258fa90e4318a413751df Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Sun, 26 Jul 2015 12:55:16 +0200
Subject: [PATCH] docs: Tweak #1232 docs, update changelog

---
 docs/changelog.rst | 21 +++++++++++++++++++++
 docs/config.rst    | 24 +++++++++++++++++++++---
 mopidy/ext.py      | 12 ++++++------
 3 files changed, 48 insertions(+), 9 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 8648dd8c..fb587c6c 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -57,6 +57,27 @@ Models
 - Added :attr:`mopidy.models.Artist.sortname` field that is mapped to
   ``musicbrainz-sortname`` tag. (Fixes: :issue:`940`)
 
+Configuration
+-------------
+
+- Add new configurations to set base directories to be used by Mopidy and
+  Mopidy extensions: :confval:`core/cache_dir`, :confval:`core/config_dir`, and
+  :confval:`core/data_dir`. (Fixes: :issue:`843`, PR: :issue:`1232`)
+
+Extension support
+-----------------
+
+- Add new methods to :class:`~mopidy.ext.Extension` class for getting cache,
+  config and data dirs specific to your extension:
+
+  - :meth:`mopidy.ext.Extension.get_cache_dir`
+  - :meth:`mopidy.ext.Extension.get_config_dir`
+  - :meth:`mopidy.ext.Extension.get_data_dir`
+
+  Extensions should use these methods so that the correct directories are used
+  both when Mopidy is run by a regular user and when run as a system service.
+  (Fixes: :issue:`843`, PR: :issue:`1232`)
+
 MPD frontend
 ------------
 
diff --git a/docs/config.rst b/docs/config.rst
index b6be6cfa..26304176 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -63,15 +63,33 @@ Core configuration
 
 .. confval:: core/cache_dir
 
-    Path to directory for storing cached information.
+    Path to base directory for storing cached data.
+
+    When running Mopidy as a regular user, this should usually be
+    ``$XDG_CACHE_DIR/mopidy``, i.e. :file:`~/.cache/mopidy`.
+
+    When running Mopidy as a system service, this should usually be
+    :file:`/var/cache/mopidy`.
 
 .. confval:: core/config_dir
 
-    Path to directory with configuration files.
+    Path to base directory for config files.
+
+    When running Mopidy as a regular user, this should usually be
+    ``$XDG_CONFIG_DIR/mopidy``, i.e. :file:`~/.config/mopidy`.
+
+    When running Mopidy as a system service, this should usually be
+    :file:`/etc/mopidy`.
 
 .. confval:: core/data_dir
 
-    Path to directory with data files.
+    Path to base directory for persistent data files.
+
+    When running Mopidy as a regular user, this should usually be
+    ``$XDG_DATA_DIR/mopidy``, i.e. :file:`~/.local/share/mopidy`.
+
+    When running Mopidy as a system service, this should usually be
+    :file:`/var/lib/mopidy`.
 
 .. confval:: core/max_tracklist_length
 
diff --git a/mopidy/ext.py b/mopidy/ext.py
index cdaa5662..908b6d5d 100644
--- a/mopidy/ext.py
+++ b/mopidy/ext.py
@@ -61,9 +61,9 @@ class Extension(object):
         return schema
 
     def get_cache_dir(self, config):
-        """Get or create cache directory for extension and return path
+        """Get or create cache directory for the extension.
 
-        :param config: Loaded configuration
+        :param config: the Mopidy config object
         :return: string
         """
         assert self.ext_name is not None
@@ -73,9 +73,9 @@ class Extension(object):
         return cache_dir_path
 
     def get_config_dir(self, config):
-        """Get or create configuration directory for extension and return path
+        """Get or create configuration directory for the extension.
 
-        :param config: Loaded configuration
+        :param config: the Mopidy config object
         :return: string
         """
         assert self.ext_name is not None
@@ -85,9 +85,9 @@ class Extension(object):
         return config_dir_path
 
     def get_data_dir(self, config):
-        """Get or create data directory for extension and return path
+        """Get or create data directory for the extension.
 
-        :param config: Loaded configuration
+        :param config: the Mopidy config object
         :returns: string
         """
         assert self.ext_name is not None