Updated documentation

Signed-off-by: Jim Easterbrook <jim@jim-easterbrook.me.uk>

src/doc/guides/getstarted.rst

@@ -326,6 +326,9 @@ Set some configuration options
 After running :py:mod:`pywws.logdata` there should be a configuration file in your data directory called 'weather.ini'.
 Open this with a text editor. You should find something like the following::
 
+   [paths]
+   work = /tmp/pywws
+
    [config]
    usb activity margin = 3.0
    ws type = 1080
@@ -342,6 +345,9 @@ If you prefer to use midnight, winter or summer, you should use ``0, True``.
 
 After editing, your weather.ini file should look something like this::
 
+   [paths]
+   work = /tmp/pywws
+
    [config]
    usb activity margin = 3.0
    ws type = 1080

src/doc/guides/hourlylogging.rst

@@ -57,10 +57,12 @@ You should have a ``[paths]`` section similar to the following (where ``xxx`` is
   work = /tmp/pywws
   templates = /home/xxx/weather/templates/
   graph_templates = /home/xxx/weather/graph_templates/
-  local_files = /home/xxx/weather/results/
+  modules = /home/xxx/weather/modules/
 
 Edit these to suit your installation and preferences.
-``work`` is a temporary directory used to store intermediate files, ``templates`` is the directory where you keep your text template files, ``graph_templates`` is the directory where you keep your graph template files, and ``local_files`` is a directory where template output that is not uploaded to your web site is put.
+``work`` is a temporary directory used to store intermediate files.
+If your computer uses solid state storage, such as a Raspberry Pi's SD card, it's a good idea to make this a "RAM disk" to reduce storage "wear".
+``templates`` is the directory where you keep your text template files, ``graph_templates`` is the directory where you keep your graph template files, and ``modules`` is a directory for any extra modules you write.
 Don't use the pywws example directories for your templates, as they will get over-written when you upgrade pywws.
 
 Copy your text and graph templates to the appropriate directories.
@@ -86,8 +88,8 @@ In weather.ini you should have ``[live]``, ``[logged]``, ``[hourly]``, ``[12 hou
 These specify what :py:mod:`pywws.hourly` should do when it is run.
 Tasks in the ``[live]`` and ``[logged]`` sections are done when there is new logged data, tasks in the ``[hourly]`` section are done every hour, tasks in the ``[12 hourly]`` section are done twice daily and tasks in the ``[daily]`` section are done once per day.
 
-The ``services`` entry is a list of online weather services to upload data to.
-The ``plot`` and ``text`` entries are lists of template files for plots and text files to be processed and, optionally, uploaded to your web site.
+The ``plot`` and ``text`` entries are lists of template files for plots and text files to be processed.
+The ``services`` entry is a list of online weather services to upload data and files to.
 Add the names of your template files and weather services to the appropriate entries, for example::
 
    [logged]
@@ -96,22 +98,24 @@ Add the names of your template files and weather services to the appropriate ent
    text = []
 
    [hourly]
-   services = []
+   services = [('twitter', 'tweet.txt'), ('ftp', '7days.png'),
+               ('ftp', '24hrs.png'), ('ftp', 'rose_24hrs.png'),
+               ('ftp', '24hrs.txt'), ('ftp', '6hrs.txt'), ('ftp', '7days.txt')]
    plot = ['7days.png.xml', '24hrs.png.xml', 'rose_24hrs.png.xml']
-   text = [('tweet.txt', 'T'), '24hrs.txt', '6hrs.txt', '7days.txt']
+   text = ['tweet.txt', '24hrs.txt', '6hrs.txt', '7days.txt']
 
    [12 hourly]
    services = []
    plot = []
    text = []
 
    [daily]
-   services = []
+   services = [('twitter', 'forecast.txt'), ('ftp', '28days.png'),
+               ('ftp', 'allmonths.txt')]
    plot = ['28days.png.xml']
-   text = [('forecast.txt', 'T'), 'allmonths.txt']
-
-Note the use of the ``'T'`` flag -- this tells pywws to send the template result to Twitter instead of uploading it to your ftp site.
+   text = ['forecast.txt', 'allmonths.txt']
 
+Note that the ``twitter`` and ``ftp`` "services" use files generated by the ``plot`` and ``text`` items.
 It's probably best not to add all of these at once.
 You could start by uploading one file to your web site, then when that's working add the remaining web site files.
 You can add Twitter and other services later on.
@@ -124,13 +128,6 @@ You can test that things are working by removing the ``[last update]`` section f
    If you need more flexibility in when tasks are done you can use ``[cron name]`` sections.
    See :doc:`weather_ini` for more detail.
 
-.. versionchanged:: 13.06_r1015
-   added the ``'T'`` flag.
-   Previously Twitter templates were listed separately in ``twitter`` entries in the ``[hourly]`` and other sections.
-
-.. versionchanged:: 13.05_r1009
-   the last update information was previously stored in weather.ini, with ``last update`` entries in several sections.
-
 Run as a cron job
 -----------------
 
@@ -142,21 +139,21 @@ For example, to run :py:mod:`pywws.hourly` every hour, at zero minutes past the
 
 This might work, but if it didn't you probably won't get any error messages to tell you what went wrong.
 It's much better to run a script that runs :py:mod:`pywws.hourly` and then emails you any output it produces.
-Here's the script I use::
+Here's a script I've used::
 
    #!/bin/sh
    #
    # weather station logger calling script
 
    export PATH=$PATH:/usr/local/bin
 
-   if [ ! -d ~/weather/data/ ]; then
+   if [ ! -d /home/jim/weather/data/ ]; then
      exit
      fi
 
    log=/var/log/log-weather
 
-   pywws-hourly -v ~/weather/data >$log 2>&1
+   pywws-hourly -v /home/jim/weather/data >$log 2>&1
 
    # mail the log file
    /home/jim/scripts/email-log.sh $log "weather log"

src/doc/guides/livelogging.rst

@@ -57,10 +57,12 @@ You should have a ``[paths]`` section similar to the following (where ``xxx`` is
   work = /tmp/pywws
   templates = /home/xxx/weather/templates/
   graph_templates = /home/xxx/weather/graph_templates/
-  local_files = /home/xxx/weather/results/
+  modules = /home/xxx/weather/modules/
 
 Edit these to suit your installation and preferences.
-``work`` is an existing temporary directory used to store intermediate files, ``templates`` is the directory where you keep your text template files, ``graph_templates`` is the directory where you keep your graph template files, and ``local_files`` is a directory where template output that is not uploaded to your web site is put.
+``work`` is a temporary directory used to store intermediate files.
+If your computer uses solid state storage, such as a Raspberry Pi's SD card, it's a good idea to make this a "RAM disk" to reduce storage "wear".
+``templates`` is the directory where you keep your text template files, ``graph_templates`` is the directory where you keep your graph template files, and ``modules`` is a directory for any extra modules you write.
 Don't use the pywws example directories for your templates, as they will get over-written when you upgrade pywws.
 
 Copy your text and graph templates to the appropriate directories.
@@ -82,18 +84,16 @@ In weather.ini you should have a ``[live]`` section similar to the following::
 
 This section specifies what pywws should do every time it gets a new reading from the weather station, i.e. every 48 seconds.
 The ``services`` entry is a list of online weather services to upload data to, e.g. ``['underground']``.
-The ``plot`` and ``text`` entries are lists of template files for plots and text files to be processed and, optionally, uploaded to your web site.
+The ``plot`` and ``text`` entries are lists of template files for plots and text files to be processed.
 You should probably leave all of these blank except for ``services``.
 
 If you use YoWindow (http://yowindow.com/) you can add an entry to the ``[live]`` section to specify your YoWindow file, e.g.::
 
    [live]
    services = ['underground']
-   text = [('yowindow.xml', 'L')]
+   text = ['yowindow.xml']
    plot = []
 
-Note the use of the ``'L'`` flag -- this tells pywws to copy the template result to your "local files" directory instead of uploading it to your ftp site.
-
 If you don't already have them, create four more sections in your weather.ini file: ``[logged]``, ``[hourly]``, ``[12 hourly]`` and ``[daily]``.
 These sections should have similar entries to the ``[live]`` section, and specify what to do every time data is logged (5 to 30 minutes, depending on your logging interval), every hour, twice daily and once per day.
 Add the names of your template files to the appropriate entries, for example::
@@ -104,22 +104,24 @@ Add the names of your template files to the appropriate entries, for example::
    text = []
 
    [hourly]
-   services = []
+   services = [('twitter', 'tweet.txt'), ('ftp', '7days.png'),
+               ('ftp', '24hrs.png'), ('ftp', 'rose_24hrs.png'),
+               ('ftp', '24hrs.txt'), ('ftp', '6hrs.txt'), ('ftp', '7days.txt')]
    plot = ['7days.png.xml', '24hrs.png.xml', 'rose_24hrs.png.xml']
-   text = [('tweet.txt', 'T'), '24hrs.txt', '6hrs.txt', '7days.txt']
+   text = ['tweet.txt', '24hrs.txt', '6hrs.txt', '7days.txt']
 
    [12 hourly]
    services = []
    plot = []
    text = []
 
    [daily]
-   services = []
+   services = [('twitter', 'forecast.txt'), ('ftp', '28days.png'),
+               ('ftp', 'allmonths.txt')]
    plot = ['28days.png.xml']
-   text = [('forecast.txt', 'T'), 'allmonths.txt']
-
-Note the use of the ``'T'`` flag -- this tells pywws to send the template result to Twitter instead of uploading it to your ftp site.
+   text = ['forecast.txt', 'allmonths.txt']
 
+Note that the ``twitter`` and ``ftp`` "services" use files generated by the ``plot`` and ``text`` items.
 It's probably best not to add all of these at once.
 You could start by uploading one file to your web site, then when that's working add the remaining web site files.
 You can add Twitter and other services later on.
@@ -129,14 +131,6 @@ You can add Twitter and other services later on.
    If you need more flexibility in when tasks are done you can use ``[cron name]`` sections.
    See :doc:`weather_ini` for more detail.
 
-.. versionchanged:: 13.06_r1015
-   added the ``'T'`` flag.
-   Previously Twitter templates were listed separately in ``twitter`` entries in the ``[hourly]`` and other sections.
-
-.. versionchanged:: 13.05_r1013
-   added a ``'yowindow.xml'`` template.
-   Previously yowindow files were generated by a separate module, invoked by a ``yowindow`` entry in the ``[live]`` section.
-
 Create a dedicated user (optional)
 ----------------------------------
 
@@ -183,21 +177,21 @@ After starting ``sudo service pywws status`` shows if it's running OK, and the l
    jim@gordon:~ $ sudo service pywws status
    ● pywws.service - pywws weather station live logging
       Loaded: loaded (/etc/systemd/system/pywws.service; static; vendor preset: enabled)
-      Active: active (running) since Sat 2018-06-02 12:06:46 BST; 1h 8min ago
-    Main PID: 15410 (pywws-livelog)
+      Active: active (running) since Thu 2018-08-23 17:49:01 BST; 12min ago
+    Main PID: 30946 (pywws-livelog)
       CGroup: /system.slice/pywws.service
-              └─15410 /usr/bin/python3 /usr/local/bin/pywws-livelog -v -l systemd /home/pywws/data/
-
-   Jun 02 12:07:48 gordon pywws-livelog[15410]: pywws.totwitter:OK
-   Jun 02 12:09:08 gordon pywws-livelog[15410]: pywws.service.cwop:OK
-   Jun 02 12:09:08 gordon pywws-livelog[15410]: pywws.service.wetterarchivde:server response "{'version': '6.0', 'status': 'SUCCESS'}"
-   Jun 02 12:09:15 gordon pywws-livelog[15410]: pywws.service.metoffice:OK
-   Jun 02 12:24:12 gordon pywws-livelog[15410]: pywws.weatherstation:setting station clock 12.1538
-   Jun 02 12:24:12 gordon pywws-livelog[15410]: pywws.weatherstation:station clock drift -0.092607 -0.344421
-   Jun 02 13:00:21 gordon pywws-livelog[15410]: Warning: empty y range [0:0], adjusting to [0:1]
-   Jun 02 13:00:21 gordon pywws-livelog[15410]: Warning: empty y2 range [0:0], adjusting to [0:1]
-   Jun 02 13:00:25 gordon pywws-livelog[15410]: Warning: empty y range [0:0], adjusting to [0:1]
-   Jun 02 13:00:25 gordon pywws-livelog[15410]: Warning: empty y2 range [0:0], adjusting to [0:1]
+              └─30946 /usr/bin/python3 /usr/local/bin/pywws-livelog -v -l systemd /home/pywws/data/
+
+   Aug 23 17:49:44 gordon pywws-livelog[30946]: pywws.service.wetterarchivde:server response "{'version': '6.0', 'status': 'SUCCESS'}"
+   Aug 23 17:49:44 gordon pywws-livelog[30946]: pywws.service.metoffice:OK
+   Aug 23 17:49:45 gordon pywws-livelog[30946]: pywws.service.openweathermap:OK
+   Aug 23 17:49:46 gordon pywws-livelog[30946]: pywws.service.cwop:OK
+   Aug 23 17:49:46 gordon pywws-livelog[30946]: pywws.service.underground:server response "success"
+   Aug 23 17:57:41 gordon pywws-livelog[30946]: pywws.weatherstation:setting sensor clock 5.33264
+   Aug 23 17:57:41 gordon pywws-livelog[30946]: pywws.weatherstation:sensor clock drift 1.4672 1.08387
+   Aug 23 18:00:25 gordon pywws-livelog[30946]: pywws.service.mastodon:OK
+   Aug 23 18:00:26 gordon pywws-livelog[30946]: pywws.service.twitter:OK
+   Aug 23 18:00:26 gordon pywws-livelog[30946]: pywws.service.sftp:OK
    jim@gordon:~ $
 
 The udev_ system can be used to start the pywws service when the computer boots or the weather station is plugged into the USB port.

src/pywws/__init__.py

@@ -1,3 +1,3 @@
 __version__ = '18.8.0'
-_release = '1587'
-_commit = '40be4b4'
+_release = '1588'
+_commit = 'a49f727'