.. _getting_started:

Getting Started
===============

Overview
--------



Requirements
------------

``django-shortwave`` requires Python 2.4 or newer and a functional
installation of Django 1.2 or newer. Further, the Django admin must be
installed. (It most likely is.)


Installation
------------

The Package
~~~~~~~~~~~

To install this package, run the following command at the root of the
package directory::

    python setup.py install

If you have the Python ``pip`` utility available, you can
also type the following to download and install in one step::

    pip install django-shortwave

Or if you prefer using ``easy_install``::

    easy_install django-shortwave

Or if you’d prefer you can simply place the included ``shortwave``
directory somewhere on your Python path, or symlink to it from
somewhere on your Python path; this is useful if you’re working from a
Git checkout. (Source code is on GitHub_.)

.. _GitHub: https://github.com/benspaulding/django-shortwave/

You can now install the app in your Django project.


The App
~~~~~~~

First, add ``shortwave`` to your installed apps::

    INSTALLED_APPS = (
        …
        'django.contrib.admin',
        'shortwave',
        …
    )

Next, add ``shortwave.urls`` to your ``urlpatterns``::

    urlpatterns = patterns('',
        …
        (r'^admin/', include(admin.site.urls)),
        (r'^shortwave/', include('shortwave.urls')),
        …
    )

Finally, add the appropriate tables to your database by running the Django
``syncdb`` management command.


Usage
-----

After reading through the `Shortwave homepage`_ and the `default commands
file`_, visit `<your_site>/<admin_url>/shortwave/wave/add/`. Here you can
create a custom wave file. At a minimum you must choose a user. You can
change options and add more commands later. Click “Save and continue editing”.

The wave is saved and can now be viewed in its raw form by click the “View on
site” link at the top of the page. Copy the URL of the raw wave file, and
provide that to Shortwave_. Then save the bookmark as it instructs you to.

.. _Shortwave: http://shortwaveapp.com/
.. _Shortwave homepage: Shortwave_
.. _default commands file: http://shortwaveapp.com/waves.txt


Support
-------

Bugs and feature requests regarding ``django-shortwave`` can be submitted to
the `GitHub issue tracker`_. Questions regarding Shortwave_ itself should be
directed to its creator, `Shaun Inman`_

.. _GitHub issue tracker: https://github.com/benspaulding/django-shortwave/issues/
.. _Shaun Inman: http://shauninman.com/

This package does not yet have a complete test suite, but it will be completed
in the near future.
