diff --git a/docs/api/models.rst b/docs/api/models.rst
new file mode 100644
index 00000000..75f9ab02
--- /dev/null
+++ b/docs/api/models.rst
@@ -0,0 +1,8 @@
+*********************************************
+:mod:`mopidy.models` -- Immutable data models
+*********************************************
+
+.. automodule:: mopidy.models
+ :synopsis: Immutable data models.
+ :members:
+ :undoc-members:
diff --git a/docs/conf.py b/docs/conf.py
index f0d29003..8cb63290 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -16,13 +16,13 @@ import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.append(os.path.abspath('.'))
+sys.path.append(os.path.abspath(os.path.dirname(__file__) + '/../'))
# -- General configuration -----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -147,7 +147,7 @@ html_static_path = ['_static']
#html_split_index = False
# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
+html_show_sourcelink = False
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
diff --git a/docs/development.rst b/docs/development.rst
index 68239393..959dcd58 100644
--- a/docs/development.rst
+++ b/docs/development.rst
@@ -6,6 +6,15 @@ Development of Mopidy is coordinated through the IRC channel ``#mopidy`` at
``irc.freenode.net`` and through `GitHub `_.
+API documentation
+=================
+
+.. toctree::
+ :glob:
+
+ api/*
+
+
Scope
=====
diff --git a/docs/index.rst b/docs/index.rst
index 08a9dacd..7c618dc3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,5 +14,6 @@ Indices and tables
==================
* :ref:`genindex`
+* :ref:`modindex`
* :ref:`search`
diff --git a/mopidy/models.py b/mopidy/models.py
index bd47c1ef..d81dfe4f 100644
--- a/mopidy/models.py
+++ b/mopidy/models.py
@@ -1,20 +1,40 @@
from copy import copy
class Artist(object):
+ """
+ :param uri: artist URI
+ :type uri: string
+ :param name: artist name
+ :type name: string
+ """
+
def __init__(self, uri=None, name=None):
self._uri = None
self._name = name
@property
def uri(self):
+ """The artist URI. Read-only."""
return self._uri
@property
def name(self):
+ """The artist name. Read-only."""
return self._name
class Album(object):
+ """
+ :param uri: album URI
+ :type uri: string
+ :param name: album name
+ :type name: string
+ :param artists: album artists
+ :type artists: list of :class:`Artist`
+ :param num_tracks: number of tracks in album
+ :type num_tracks: integer
+ """
+
def __init__(self, uri=None, name=None, artists=None, num_tracks=0):
self._uri = uri
self._name = name
@@ -23,22 +43,45 @@ class Album(object):
@property
def uri(self):
+ """The album URI. Read-only."""
return self._uri
@property
def name(self):
+ """The album name. Read-only."""
return self._name
@property
def artists(self):
+ """List of :class:`Artist` elements. Read-only."""
return copy(self._artists)
@property
def num_tracks(self):
+ """The number of tracks in the album. Read-only."""
return self._num_tracks
class Track(object):
+ """
+ :param uri: track URI
+ :type uri: string
+ :param title: track title
+ :type title: string
+ :param artists: track artists
+ :type artists: list of :class:`Artist`
+ :param album: track album
+ :type album: :class:`Album`
+ :param track_no: track number in album
+ :type track_no: integer
+ :param date: track release date
+ :type date: :class:`datetime.date`
+ :param length: track length in milliseconds
+ :type length: integer
+ :param id: track ID (unique and non-changing as long as the process lives)
+ :type id: integer
+ """
+
def __init__(self, uri=None, title=None, artists=None, album=None,
track_no=0, date=None, length=None, id=None):
self._uri = uri
@@ -52,37 +95,52 @@ class Track(object):
@property
def uri(self):
+ """The track URI. Read-only."""
return self._uri
@property
def title(self):
+ """The track title. Read-only."""
return self._title
@property
def artists(self):
+ """List of :class:`Artist`. Read-only."""
return copy(self._artists)
@property
def album(self):
+ """The track :class:`Album`. Read-only."""
return self._album
@property
def track_no(self):
+ """The track number in album. Read-only."""
return self._track_no
@property
def date(self):
+ """The track release date. Read-only."""
return self._date
@property
def length(self):
+ """The track length in milliseconds. Read-only."""
return self._length
@property
def id(self):
+ """The track ID. Read-only."""
return self._id
def mpd_format(self, position=0):
+ """
+ Format track for output to MPD client.
+
+ :param position: track's position in playlist
+ :type position: integer
+ :rtype: list of two-tuples
+ """
return [
('file', self.uri),
('Time', self.length // 1000),
@@ -96,10 +154,24 @@ class Track(object):
]
def mpd_format_artists(self):
+ """
+ Format track artists for output to MPD client.
+
+ :rtype: string
+ """
return u', '.join([a.name for a in self.artists])
class Playlist(object):
+ """
+ :param uri: playlist URI
+ :type uri: string
+ :param name: playlist name
+ :type name: string
+ :param tracks: playlist's tracks
+ :type tracks: list of :class:`Track` elements
+ """
+
def __init__(self, uri=None, name=None, tracks=None):
self._uri = uri
self._name = name
@@ -107,21 +179,30 @@ class Playlist(object):
@property
def uri(self):
+ """The playlist URI. Read-only."""
return self._uri
@property
def name(self):
+ """The playlist name. Read-only."""
return self._name
@property
def tracks(self):
+ """List of :class:`Track` elements. Read-only."""
return copy(self._tracks)
@property
def length(self):
+ """The number of tracks in the playlist. Read-only."""
return len(self._tracks)
def mpd_format(self, start=0, end=None):
+ """
+ Format playlist for output to MPD client.
+
+ :rtype: list of lists of two-tuples
+ """
if end is None:
end = self.length
tracks = []