From 13796b1e429430124daa04fe4ab3c10f544e6fc4 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 9 Mar 2010 19:46:48 +0100 Subject: [PATCH] docs: Split development docs intro three pages. Extend roadmap part quite a bit. --- .../contributing.rst} | 74 +------------------ docs/development/index.rst | 10 +++ docs/development/internals.rst | 68 +++++++++++++++++ docs/development/roadmap.rst | 53 +++++++++++++ docs/index.rst | 2 +- 5 files changed, 135 insertions(+), 72 deletions(-) rename docs/{development.rst => development/contributing.rst} (50%) create mode 100644 docs/development/index.rst create mode 100644 docs/development/internals.rst create mode 100644 docs/development/roadmap.rst diff --git a/docs/development.rst b/docs/development/contributing.rst similarity index 50% rename from docs/development.rst rename to docs/development/contributing.rst index 4cb043f6..2889c210 100644 --- a/docs/development.rst +++ b/docs/development/contributing.rst @@ -1,20 +1,11 @@ -*********** -Development -*********** +***************** +How to contribute +***************** Development of Mopidy is coordinated through the IRC channel ``#mopidy`` at ``irc.freenode.net`` and through `GitHub `_. -Scope for the first release -=========================== - -To limit scope, we will start by implementing an MPD server which only -supports Spotify, and not playback of files from disk. We will make Mopidy -modular, so we can extend it with other backends in the future, like file -playback and other online music services such as Last.fm. - - Code style ========== @@ -94,62 +85,3 @@ The documentation at http://www.mopidy.com/docs/ is automatically updated within 10 minutes after a documentation update is pushed to ``jodal/mopidy/master`` at GitHub. - -Notes on despotify/spytify -========================== - -`spytify `_ -is the Python bindings for the open source `despotify `_ -library. It got no documentation to speak of, but a couple of examples are -available. - -A list of the issues we currently experience with spytify, both bugs and -features we wished was there: - -* r483: Sometimes segfaults when traversing stored playlists, their tracks, - artists, and albums. As it is not predictable, it may be a concurrency issue. - -* r503: Segfaults when looking up playlists, both your own lists and other - peoples shared lists. To reproduce:: - - >>> import spytify - >>> s = spytify.Spytify('alice', 'secret') - >>> s.lookup('spotify:user:klette:playlist:5rOGYPwwKqbAcVX8bW4k5V') - Segmentation fault - - -Notes on libspotify/libopenspotify/pyspotify -============================================ - -`pyspotify `_ is the Python bindings for -the official Spotify library, libspotify. It got no documentation to speak of, -but multiple examples are available. - -A list of the issues we currently experience with pyspotify, both bugs and -features we wished was there: - -* None at the moment. - - -Class instantiation and usage -============================= - -The following diagram shows how Mopidy with the despotify backend and ALSA -mixer is wired together. The gray nodes are part of external dependencies, and -not Mopidy. - -.. digraph:: class_instantiation_and_usage - - "spytify" [ color="gray" ] - "despotify" [ color="gray" ] - "alsaaudio" [ color="gray" ] - "__main__" -> "MpdServer" [ label="create 1" ] - "__main__" -> "AlsaMixer" [ label="create 1" ] - "__main__" -> "DespotifyBackend" [ label="create 1" ] - "MpdServer" -> "MpdSession" [ label="create 1 per client" ] - "MpdSession" -> "MpdHandler" [ label="pass MPD requests to" ] - "MpdHandler" -> "DespotifyBackend" [ label="use backend API" ] - "DespotifyBackend" -> "spytify" [ label="use Python wrapper" ] - "spytify" -> "despotify" [ label="use C library" ] - "DespotifyBackend" -> "AlsaMixer" [ label="use mixer API" ] - "AlsaMixer" -> "alsaaudio" [ label="use Python library" ] diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 00000000..14c49dbd --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,10 @@ +*********** +Development +*********** + +.. toctree:: + :maxdepth: 3 + + roadmap + contributing + internals diff --git a/docs/development/internals.rst b/docs/development/internals.rst new file mode 100644 index 00000000..8764d74e --- /dev/null +++ b/docs/development/internals.rst @@ -0,0 +1,68 @@ +********* +Internals +********* + +Some of the following notes and details will hopefully be useful when you start +developing on Mopidy, while some may only be useful when you get deeper into +specific parts of Mopidy. + + +Class instantiation and usage +============================= + +The following diagram shows how Mopidy with the despotify backend and ALSA +mixer is wired together. The gray nodes are part of external dependencies, and +not Mopidy. + +.. digraph:: class_instantiation_and_usage + + "spytify" [ color="gray" ] + "despotify" [ color="gray" ] + "alsaaudio" [ color="gray" ] + "__main__" -> "MpdServer" [ label="create 1" ] + "__main__" -> "AlsaMixer" [ label="create 1" ] + "__main__" -> "DespotifyBackend" [ label="create 1" ] + "MpdServer" -> "MpdSession" [ label="create 1 per client" ] + "MpdSession" -> "MpdHandler" [ label="pass MPD requests to" ] + "MpdHandler" -> "DespotifyBackend" [ label="use backend API" ] + "DespotifyBackend" -> "spytify" [ label="use Python wrapper" ] + "spytify" -> "despotify" [ label="use C library" ] + "DespotifyBackend" -> "AlsaMixer" [ label="use mixer API" ] + "AlsaMixer" -> "alsaaudio" [ label="use Python library" ] + + +Notes on despotify/spytify +========================== + +`spytify `_ +is the Python bindings for the open source `despotify `_ +library. It got no documentation to speak of, but a couple of examples are +available. + +A list of the issues we currently experience with spytify, both bugs and +features we wished was there: + +- r503: Sometimes segfaults when traversing stored playlists, their tracks, + artists, and albums. As it is not predictable, it may be a concurrency issue. + +- r503: Segfaults when looking up playlists, both your own lists and other + peoples shared lists. To reproduce:: + + >>> import spytify + >>> s = spytify.Spytify('alice', 'secret') + >>> s.lookup('spotify:user:klette:playlist:5rOGYPwwKqbAcVX8bW4k5V') + Segmentation fault + + +Notes on libspotify/pyspotify +============================================ + +`pyspotify `_ is the Python bindings for +the official Spotify library, libspotify. It got no documentation to speak of, +but multiple examples are available. Like libspotify, pyspotify's calls are +mostly asynchronous. + +A list of the issues we currently experience with pyspotify, both bugs and +features we wished was there: + +- None at the moment. diff --git a/docs/development/roadmap.rst b/docs/development/roadmap.rst new file mode 100644 index 00000000..26861b06 --- /dev/null +++ b/docs/development/roadmap.rst @@ -0,0 +1,53 @@ +******* +Roadmap +******* + +This is the current roadmap and collection of wild ideas for future Mopidy +development. + + +Scope for the first release +=========================== + +This was was the plan written down when we started developing Mopidy, and we +still keep quite close to it: + + To limit scope, we will start by implementing an MPD server which only + supports Spotify, and not playback of files from disk. We will make Mopidy + modular, so we can extend it with other backends in the future, like file + playback and other online music services such as Last.fm. + + +Stuff we really want to do, but just not right now +================================================== + +- Replace libspotify with `openspotify + `_ for the + ``LibspotifyBackend``. +- A backend for playback from local disk. Quite a bit of work on a `gstreamer + `_ backend has already been done by Thomas + Adamcik. +- Support multiple backends at the same time. It would be really nice to have + tracks from local disk and Spotify tracks in the same playlist. +- Package Mopidy as a `Python package `_. +- Get a build server, i.e. `Hudson `_, up and running + which runs our test suite on all relevant platforms (Ubuntu, OS X, etc.) and + creates nightly packages (see next items). +- Create `Debian packages `_ of all our + dependencies and Mopidy itself (hosted in our own Debian repo until we get + stuff into the various distros) to make Debian/Ubuntu installation a breeze. +- Create `Homebrew `_ recipies for all our + dependencies and Mopidy itself to make OS X installation a breeze. + + +Crazy stuff we had to write down somewhere +========================================== + +- Add or create a new frontend protocol other than MPD. The MPD protocol got + quite a bit of legacy and it is badly documented. The amount of available + client implementations is MPD's big win. +- Add support for storing (Spotify) music to disk. +- Add support for serving the music as an `Icecast `_ + stream instead of playing it locally. +- Integrate with `Squeezebox `_ in some + way. diff --git a/docs/index.rst b/docs/index.rst index 29b9b928..644b8d57 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,7 @@ Contents :maxdepth: 3 installation/index - development + development/index api/index changes