
How to configure pywws to post messages to Twitter
**************************************************

1. Install dependencies.

   * Python 2.5+ - http://python.org/ (Note: Python 3 is not
     supported.)

   * tweepy - http://code.google.com/p/tweepy/

   * simplejson - http://pypi.python.org/pypi/simplejson/

   Note that simplejson is included in Python 2.6+

2. Create a Twitter account.

   You could post weather updates to your 'normal' Twitter account,
   but I think it's better to have a separate account just for weather
   reports. This could be useful to someone who lives in your area,
   but doesn't want to know what you had for breakfast.

3. Authorise pywws to post to your Twitter account.

   Make sure no other pywws software is running, then run the
   ``TwitterAuth`` program:

      python TwitterAuth.py /data/weather

   (Replace ``/data/weather`` with your data directory.)

   This will open a web browser window (or give you a URL to copy to
   your web browser) where you can log in to your Twitter account and
   authorise pywws to post. Your web browser will then show a 7 digit
   number which you need to copy to the ``TwitterAuth`` program. If
   successful, your weather.ini file will now have a ``[twitter]``
   section with ``secret`` and ``key`` entries. (Don't disclose these
   to anyone else.)

4. Add location data (optional).

   Edit your weather.ini file and add ``latitude`` and ``longitude``
   entries to the ``[twitter]`` section. For example:

      [twitter]
      secret = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      latitude = 51.501
      longitude = -0.142

5. Create a template.

   Twitter messages are generated using a template, just like creating
   files to upload to a website. Copy the example template 'tweet.txt'
   to your template directory, then test it:

      python pywws/Template.py /data/weather ~/weather/templates/tweet.txt tweet.txt
      cat tweet.txt

   (Replace ``/data/weather`` and ``~/weather/templates`` with your
   data and template directories.) If you need to change the template
   (e.g. to change the units or language used) you can edit it now or
   later.

6. Post your first weather Tweet.

   Now everything is prepared for ``pywws.ToTwitter`` to be run:

      python pywws/ToTwitter.py /data/weather tweet.txt

   If this works, your new Twitter account will have posted its first
   weather report. (You should delete the tweet.txt file now.)

7. Add Twitter updates to your hourly tasks.

   Edit your weather.ini file and edit the ``[hourly]`` section. For
   example:

      [hourly]
      services = []
      twitter = ['tweet.txt']
      plot = ['7days.png.xml', '24hrs.png.xml', 'rose_12hrs.png.xml']
      text = ['24hrs.txt', '6hrs.txt', '7days.txt', 'allmonths.txt ']

   You could change the ``[logged]``, ``[12 hourly]`` or ``[daily]``
   sections instead, but I think ``[hourly]`` is most appropriate for
   Twitter updates.

   Comments or questions? Please subscribe to the pywws mailing list
   http://groups.google.com/group/pywws and let us know.
