Doc dump.

docs/api.rst

@@ -31,9 +31,18 @@ Request
     :inherited-members:
 
 
+Actions
+-------
+
+.. automodule:: xbmcswift2.actions
+    :members:
+
+
 Extended API
 ------------
 
+.. module:: xbmcswift2 
+
 Module
 ``````
 

docs/caching.rst

@@ -8,6 +8,13 @@ xbmcswift2 offers a few options for caching and storage to help improve the
 user experience of your addon. swift offers a simple storage mechanism that
 allows you to store arbitraty python objects to use between requests.
 
+.. warning::
+
+    The current implementation of xbmcswift2's storage is very basic and is not
+    thread safe. If your addon does background calls via the context menu and
+    manipulates storages in these backgound threads, you might run into some
+    issues.
+
 Storing Arbitraty Python Objects
 --------------------------------
 
@@ -88,6 +95,10 @@ for this decorator; it defaults to 24 hours.
              cache the view. See the below section 'Caveats' for more
              information.
 
+.. warning:: It is currently only possible to attach a single cached_route to a
+             view. If you have multiple routes on a given view, try refactoring
+             some logic out to a new function that can be cached, instead of
+             using the cached_route decorator.
 Caveats
 -------
 

docs/commandline.rst

@@ -11,7 +11,7 @@ Commands
 When running xbmcswift2 from the command line, there are two commands
 available, *create* and *run*. *create* is a script that will create the basic
 scaffolding and necessary files for an XBMC addon and personalize it by asking
-a few questions. *run* enables you to debug your addon on the command line.
+you a few questions. *run* enables you to debug your addon on the command line.
 
 To see the command line help, simply execute ``xbmcswift2 -h``. Both of the
 commands are explained further below.

docs/index.rst

@@ -2,10 +2,13 @@
 Welcome to xbmcswift2's documentation!
 ======================================
 
-Welcome to the documentation for xbmcswift2. This documentation is divided into
-several parts. If you are new, you should start with the :ref:`installation`
-and then move on to :ref:`quickstart`. If you would prefer a more detailed
-walkthrough, try the :ref:`tutorial`.
+Welcome to the documentation for xbmcswift2. xbmcswift2 is a small framework to
+ease development of XBMC addons. Whether you are an experienced addon
+developer, or just coding your first addon, you'll find benefits to using xbmcswift2.
+
+This documentation is divided into several parts. If you are new, you should
+start with the :ref:`installation` and then move on to :ref:`quickstart`. If
+you would prefer a more detailed walkthrough, try the :ref:`tutorial`.
 
 To get a deeper understanding of xbmcswift2, check out :ref:`routing`,
 :ref:`caching` and the complete :ref:`api` reference. For specific code
@@ -24,6 +27,7 @@ Basic Info
     installation
     quickstart
     tutorial
+    item
     commandline
 
 Advanced User Guide

docs/installation.rst

@@ -9,23 +9,28 @@ Installation
     command line as well as in XBMC. This means that we will have to install
     xbmcswift2 twice, once for the command line and once as an XBMC addon.
 
+    The XBMC version of xbmcswift2 is a specially packaged version of the main
+    release. It excludes some CLI code and tests. It also contains XBMC
+    required files like addon.xml.
 
 The easiest way to get the most recent version of xbmcswift2 for XBMC is to
 install an addon that requires xbmcswift2. You can find a list of such addons
-on the :ref:`poweredby` page. The other options is download the correct version
-from https://github.com/jbeluch/xbmcswift2-xbmc-dist/tags and unpack it into
-your addons folder.  
+on the :ref:`poweredby` page. The other options is download the current XBMC
+distribution from https://github.com/jbeluch/xbmcswift2-xbmc-dist/tags and
+unpack it into your addons folder.  
 
 Now, on to installing xbmcswift2 for use on the command line.
 
 virtualenv
 ----------
 
 Virtualenv is an awesome tool that enables clean installation and removal of
-python libraries into a "virtual environment". Using a virtual environment
+python libraries into a sequestered environment. Using a virtual environment
 means that when you install a library, it doesn't pollute your system-wide
 python installation. This makes it possible to install different versions of a
-library in different environments and they will never conflict.
+library in different environments and they will never conflict. It's a good
+habit to get into when doing python development. So, first we're going to
+install virtualenv.
 
 If you already have pip installed, you can simply::
 
@@ -36,7 +41,7 @@ or if you only have easy_install::
     $ sudo easy_install virtualenv
 
 I also like to use some helpful virtualenv scripts, so install
-virtualenv-wrapper::
+virtualenv-wrapper as well::
 
     $ sudo pip install virtualenv-wrapper
 
@@ -47,7 +52,7 @@ Now we can create our virtualenv::
 
     $ mkvirtualenv xbmcswift2
 
-When this completes, your prompt should now be preceded by `(xbmcswift2)`. The
+When this completes, your prompt should now be prefixed by `(xbmcswift2)`. The
 new prompt signals that we are now working within our virtualenv. Any libraries
 that we install via pip will only be available in this environment. Now we'll
 install xbmcswift2::

docs/item.rst

@@ -0,0 +1,135 @@
+.. _item:
+
+
+The ListItem
+============
+
+xbmcswift2 prefers to represent XBMC list items as plain python dictionaries as
+much as possible. Views return lists of dictionaries, where each dict
+represents an XBMC listitem. The list of valid keys in an item dict can always
+be validated by reviewing the available arguments to
+:meth:`xbmcswift2.ListItem.from_dict`. However, we'll go into more detail here.
+
+Valid keys in an item dict are:
+
+* `label`_
+* `label2`_
+* `icon`_
+* `thumbnail`_
+* `path`_
+* `selected`_
+* `info`_
+* `properties`_
+* `context_menu`_
+* `replace_context_menu`_
+* `is_playable`_
+* `info_type`_
+* `stream_info`_
+
+label
+-----
+
+A required string. Used as the main display label for the list item.
+
+
+label2
+------
+
+A string. Used as the alternate display label for the list item.
+
+
+icon
+----
+
+A path to an icon image.
+
+
+thumbnail
+---------
+
+A path to a thumbnail image.
+
+
+path
+----
+
+A required string.
+
+For non-playable items, this is typically a URL for a different path in the
+same addon. To derive URLs for other views within your addon, use
+:meth:`xbmcswift2.Plugin.url_for`.
+
+For playable items, this is typically a URL to a remote media file. (One
+exception, is if you are using the set_resolved_url pattern, the URL will be
+playable but will also call back into your addon.)
+
+
+selected
+--------
+
+A boolean which will set the item as selected. False is default.
+
+
+info
+----
+
+A dictionary of key/values of metadata information about the item. See the
+`XBMC docs
+<http://mirrors.xbmc.org/docs/python-docs/xbmcgui.html#ListItem-setInfo>`_ for
+a list of valid info items. Keys are always strings but values should be the
+correct type required by XBMC.
+
+Also, see the related `info_type`_ key.
+
+
+properties
+----------
+
+A dict of properties, similar to info-labels. See
+http://mirrors.xbmc.org/docs/python-docs/xbmcgui.html#ListItem-setProperty for
+more information.
+
+
+context_menu
+------------
+
+A list of tuples, where each tuple is of length 2. The tuple should be (label,
+action) where action is a string representing a built-in XBMC function. See the
+`XBMC documentation
+<http://mirrors.xbmc.org/docs/python-docs/xbmcgui.html#ListItem-addContextMenuItems>`_
+for more details and `Using the Context Menu` for some example code.
+
+
+replace_context_menu
+--------------------
+
+Used in conjunction with `context_menu`. A boolean indicating whether to
+replace the existing context menu with the passed context menu items. Defaults
+to False.
+
+
+is_playable
+-----------
+
+A boolean indicating whether the item dict is a playable item. False indicates
+that the item is a directory item. Use True when the path is a direct media
+URL, or a URL that calls back to your addon where set_resolved_url will be
+used.
+
+
+info_type
+---------
+
+Used in conjunction with `info`. The default value is usually configured
+automatically from your addon.xml. See
+http://mirrors.xbmc.org/docs/python-docs/xbmcgui.html#ListItem-setInfo for
+valid values.
+
+
+stream_info
+-----------
+
+A dict where each key is a stream type and each value is another dict of stream
+values. See
+http://mirrors.xbmc.org/docs/python-docs/xbmcgui.html#ListItem-addStreamInfo
+for more information.

docs/poweredby.rst

@@ -7,87 +7,28 @@ Addons Powered by xbmcswift2
 Want your addon included here? Send me an email at web@jonathanbeluch.com with
 your addon name and a link to a repository (XBMC's git repo is fine).
 
-Academic Earth
---------------
-
-Watch lectures from Academic Earth within the XBMC interface.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.video.academicearth/>`_
-* `view source <https://github.com/jbeluch/xbmc-academic-earth>`_
-
-Documentary.net
----------------
-
-Watch documentaries from http://documentary.net.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.video.documentary.net/>`_
-* `view source <https://github.com/jbeluch/plugin.video.documentary.net>`_
-
-VimCasts
---------
-
-Watch screencasts from http://vimcasts.org.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.video.vimcasts/>`_
-* `view source <https://github.com/jbeluch/xbmc-vimcasts>`_
-
-
-Radio
------
-
-Music plugin to access over 4000 international radio broadcasts from rad.io, radio.de and radio.fr.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.audio.radio_de/>`_
-* `view source <https://github.com/dersphere/plugin.audio.radio_de>`_
-
-
-Shoutcast 2
------------
-
-Browse more than 50.000 free internet radio stations.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.audio.shoutcast>`_
-* `view source <https://github.com/dersphere/plugin.audio.shoutcast>`_
-
-
-Cheezburger Network
--------------------
-
-Cheezburger: All your funny in one place.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.image.cheezburger_network>`_
-* `view source <https://github.com/dersphere/plugin.image.cheezburger_network>`_
-
-
-Apple Itunes Podcasts
----------------------
-
-Browse and search for thousands of free audio and video podcasts.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.video.itunes_podcasts>`_
-* `view source <https://github.com/dersphere/plugin.video.itunes_podcasts>`_
-
-
-MyZen.tv
---------
-
-Watch the Free Exercises from the well-being website www.myzen.tv.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.video.myzen_tv>`_
-* `view source <https://github.com/dersphere/plugin.video.myzen_tv>`_
-
-Rofl.to
--------
-
-Daily updated funny videos + clips. Your #1 resource for fun videos.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.video.rofl_to>`_
-* `view source <https://github.com/dersphere/plugin.video.rofl_to>`_
-
-Wimp
-----
-
-A collection of the best online videos. Our editors make sure clips added are family friendly.
-
-* `info <http://xbmcaddonbrowser.com/addons/eden/plugin.video.wimp>`_
-* `view source <https://github.com/dersphere/plugin.video.wimp>`_
+========================    =============================================================
+Addon                       Source
+========================    =============================================================
+`Academic Earth`_           https://github.com/jbeluch/xbmc-academic-earth
+`Documentary.net`_          https://github.com/jbeluch/plugin.video.documentary.net
+`VimCasts`_                 https://github.com/jbeluch/xbmc-vimcasts
+`Radio`_                    https://github.com/dersphere/plugin.audio.radio_de
+`Shoutcast 2`_              https://github.com/dersphere/plugin.audio.shoutcast
+`Cheezburger Network`_      https://github.com/dersphere/plugin.image.cheezburger_network
+`Apple Itunes Podcasts`_    https://github.com/dersphere/plugin.video.itunes_podcasts
+`MyZen.tv`_                 https://github.com/dersphere/plugin.video.myzen_tv
+`Rofl.to`_                  https://github.com/dersphere/plugin.video.rofl_to
+`Wimp`_                     https://github.com/dersphere/plugin.video.wimp
+========================    =============================================================
+
+.. _Academic Earth: http://xbmcaddonbrowser.com/addons/frodo/plugin.video.academicearth/
+.. _Documentary.net: http://xbmcaddonbrowser.com/addons/frodo/plugin.video.documentary.net/
+.. _VimCasts: http://xbmcaddonbrowser.com/addons/frodo/plugin.video.vimcasts/
+.. _Radio: http://xbmcaddonbrowser.com/addons/frodo/plugin.audio.radio_de/
+.. _Shoutcast 2: http://xbmcaddonbrowser.com/addons/frodo/plugin.audio.shoutcast
+.. _Cheezburger Network: http://xbmcaddonbrowser.com/addons/frodo/plugin.image.cheezburger_network
+.. _Apple Itunes Podcasts: http://xbmcaddonbrowser.com/addons/frodo/plugin.video.itunes_podcasts
+.. _MyZen.tv: http://xbmcaddonbrowser.com/addons/frodo/plugin.video.myzen_tv
+.. _Rofl.to: http://xbmcaddonbrowser.com/addons/frodo/plugin.video.rofl_to
+.. _Wimp: http://xbmcaddonbrowser.com/addons/frodo/plugin.video.wimp