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 = []