update docs for starttime and timezone

anuga/shallow_water/shallow_water_domain.py

@@ -1116,26 +1116,67 @@ def set_starttime(self, timestamp=0.0):
         
         Essentially we use unix time as our absolute time. So 
         time = 0 corresponds to Jan 1st 1970 UTC
+
+        Use naive datetime which will be localized to the domain timezone or
+        or use pytz.timezone.localize to set timezone of datetime.
+        Don't use the tzinfo argument of datetime to set timezone as this does not work!
         
         Example: 
         
+            Without setting timezone for the `domain` and the `starttime` then time
+            calculations are all based on UTC. Note the timestamp, which is time in seconds
+            from 1st Jan 1970 UTC.
+        
+        >>> import pytz
+        >>> import anuga
+        >>> from datetime import datetime
+        >>> 
+        >>> domain = anuga.rectangular_cross_domain(10,10)
+        >>> dt = datetime(2021,3,21,18,30)
+        >>> domain.set_starttime(dt)
+        >>> print(domain.get_datetime(), 'TZ', domain.get_timezone(), 'Timestamp: ', domain.get_time())
+        2021-03-21 18:30:00+00:00 TZ UTC Timestamp:  1616351400.0
+
+        Example:
+
+            Setting timezone for the `domain`, then naive `datetime` will be localizes to 
+            the `domain` timezone. Note the timestamp, which is time in seconds
+            from 1st Jan 1970 UTC.
+
+        >>> import pytz
+        >>> import anuga
+        >>> from datetime import datetime
+        >>> 
+        >>> domain = anuga.rectangular_cross_domain(10,10)
+        >>> AEST = pytz.timezone('Australia/Sydney')
+        >>> domain.set_timezone(AEST)
+        >>> 
+        >>> dt = datetime(2021,3,21,18,30)
+        >>> domain.set_starttime(dt)
+        >>> print(domain.get_datetime(), 'TZ', domain.get_timezone(), 'Timestamp: ', domain.get_time())
+        2021-03-21 18:30:00+11:00 TZ Australia/Sydney Timestamp:  1616311800.0
+
+        Example:
+
+            Setting timezone for the `domain`, and setting the timezone for the `datetime`. 
+            Note the timestamp, which is time in seconds from 1st Jan 1970 UTC is the same
+            as teh previous example.
+
         >>> import pytz
         >>> import anuga
         >>> from datetime import datetime
-        >>>
+        >>> 
         >>> domain = anuga.rectangular_cross_domain(10,10)
         >>> 
+        >>> ACST = pytz.timezone('Australia/Adelaide')
+        >>> domain.set_timezone(ACST)
+        >>> 
         >>> AEST = pytz.timezone('Australia/Sydney')
-        >>> # ========================================================
-        >>> # Either use naive datetime (which will default to UTC)
-        >>> # or use AEST.localize to set timezone of datetime to AEST
-        >>> # Don't use the tzinfo argument of datetime as this 
-        >>> # does not work
-        >>> # ========================================================
         >>> dt = AEST.localize(datetime(2021,3,21,18,30))
+        >>> 
         >>> domain.set_starttime(dt)
         >>> print(domain.get_datetime(), 'TZ', domain.get_timezone(), 'Timestamp: ', domain.get_time())
-        
+        2021-03-21 18:00:00+10:30 TZ Australia/Adelaide Timestamp:  1616311800.0
         """
 
 

docs/source/conf.py

@@ -21,7 +21,8 @@
 author =  'Stephen Roberts, Ole Nielsen, Gareth Davies'
 
 # The full version, including alpha/beta/rc tags
-release = '3.0.1'
+import anuga
+release = anuga.__version__
 
 
 import os

tools/install_ubuntu_travis.sh

@@ -157,6 +157,10 @@ echo "|  Using pip to install utm                     |"
 echo "+===============================================+"
 python -m pip  install -q utm
 
+echo "+===============================================+"
+echo "|  Using pip to install nbsphinx                |"
+echo "+===============================================+"
+python -m pip  install -q nbsphinx
 
 ##########################################################
 # Setup for various versions of MPI