Permalink
Browse files

Doc dump.

  • Loading branch information...
1 parent 2d1e5d2 commit 6f179a04ef0d39790d15e9a352cdf582bef2bb8e @jbeluch committed Feb 20, 2013
Showing with 201 additions and 96 deletions.
  1. +9 −0 docs/api.rst
  2. +11 −0 docs/caching.rst
  3. +1 −1 docs/commandline.rst
  4. +8 −4 docs/index.rst
  5. +12 −7 docs/installation.rst
  6. +135 −0 docs/item.rst
  7. +25 −84 docs/poweredby.rst
View
@@ -31,9 +31,18 @@ Request
:inherited-members:
+Actions
+-------
+
+.. automodule:: xbmcswift2.actions
+ :members:
+
+
Extended API
------------
+.. module:: xbmcswift2
+
Module
``````
View
@@ -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
-------
View
@@ -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.
View
@@ -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
View
@@ -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::
View
@@ -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.
View
@@ -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

0 comments on commit 6f179a0

Please sign in to comment.