docs: Tweak #1232 docs, update changelog

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

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
 

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