Merge branch 'develop'

Author: csparpa

sphinx/conf.py

@@ -15,6 +15,7 @@
 import sys
 import os
 import sphinx_readable_theme
+from recommonmark.parser import CommonMarkParser
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -32,6 +33,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'recommonmark'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -48,7 +50,7 @@
 
 # General information about the project.
 project = u'pyowm'
-copyright = u'2018, Claudio Sparpaglione'
+copyright = u'2020, Claudio Sparpaglione'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -118,16 +120,16 @@
 #html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
+html_short_title = 'PyOWM documentation'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = 'logo.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = 'favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -141,7 +143,7 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -170,7 +172,7 @@
 #html_show_sphinx = True
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -269,7 +271,7 @@
 epub_title = u'pyowm'
 epub_author = u'Claudio Sparpaglione'
 epub_publisher = u'Claudio Sparpaglione'
-epub_copyright = u'2018, Claudio Sparpaglione'
+epub_copyright = u'2020, Claudio Sparpaglione'
 
 # The basename for the epub file. It defaults to the project name.
 #epub_basename = u'pyowm'
@@ -334,5 +336,5 @@
 
 
 source_parsers = {
-   '.md': 'recommonmark.parser.CommonMarkParser',
-}
+   '.md': CommonMarkParser,
+}

sphinx/favicon.ico

@@ -666,9 +666,15 @@ The `raw_measurements_dict` contains multiple sub-dicts, each one being a a data
 
 With the OneCall Api you can get the current weather, hourly forecast for the next 48 hours and the daily forecast for the next seven days in one call.
 
-Below some examples:
+One Call objects can be thought of as datasets that "photograhp" of observed and forecasted weather data for a location: such photos are given for a specific timestamp.
 
-### What is the feels like temperature (°C) tomorrow morning?
+It is possible to get:
+  - current OneCall data: the "photo" given for today)
+  - historical OneCall data: "photos" given for past days, up to 5 
+
+### Current OneCall data
+
+#### What is the feels like temperature (°C) tomorrow morning?
 Always in Berlin:
 
 ```python
@@ -680,7 +686,7 @@ one_call = mgr.one_call(lat=52.5244, lon=13.4105)
 one_call.forecast_daily[0].temperature('celsius').get('feels_like_morn', None) #Ex.: 7.7
 ```
 
-### What's the wind speed in three hours?
+#### What's the wind speed in three hours?
 
 __Attention: The first entry in forecast_hourly is the current hour.__
 If you send the request at 18:36 UTC then the first entry in forecast_hourly is from 18:00 UTC.
@@ -696,7 +702,7 @@ one_call = mgr.one_call(lat=52.5244, lon=13.4105)
 one_call.forecast_hourly[3].wind().get('speed', 0) # Eg.: 4.42
 ```
 
-### What's the current humidity?
+#### What's the current humidity?
 
 Always in Berlin:
 
@@ -708,3 +714,54 @@ one_call = mgr.one_call(lat=52.5244, lon=13.4105)
 
 one_call.current.humidity # Eg.: 81
 ```
+
+### Historical OneCall data
+
+Remember the "photograph" metaphor for OneCall data. You can query for "photos" given for past days: when you do that,
+be aware that such a photo carries along weather forecasts (hourly and daily) that *might* refer to the past
+
+This is because - as said above - the One Call API returns hourly forecasts for a streak of 48 hours and daily forecast 
+for a streak of 7 days, both streaks beginning from the timestamp which the OneCall object refers to
+
+In case of doubt, anyway, you can always _check the reference timestamp_ for the `Weather` objects embedded into the
+OneCall object and check if it's in the past or not.
+
+
+#### What was the observed weather yesterday at this time?
+
+Always in Berlin: 
+
+```python
+from pyowm.owm import OWM
+from pyowm.utils import timestamps, formatting
+
+owm = OWM('your-api-key')
+mgr = owm.weather_manager()
+
+# what is the epoch for yesterday at this time?
+yesterday_epoch = formatting.to_UNIXtime(timestamps.yesterday())
+
+one_call_yesterday = mgr.one_call_history(lat=52.5244, lon=13.4105, dt=yesterday_epoch)
+
+observed_weather = one_call_yesterday.current
+```
+
+#### What was the weather forecasted 3 days ago for the subsequent 48 hours ?
+
+No way we move from Berlin:
+
+```python
+from pyowm.owm import OWM
+from pyowm.utils import timestamps
+from datetime import datetime, timedelta, timezone
+
+owm = OWM('your-api-key')
+mgr = owm.weather_manager()
+
+# what is the epoch for 3 days ago at this time?
+three_days_ago_epoch = int((datetime.now() - timedelta(days=3)).replace(tzinfo=timezone.utc).timestamp())
+
+one_call_three_days_ago = mgr.one_call_history(lat=52.5244, lon=13.4105, dt=three_days_ago_epoch)
+
+list_of_forecasted_weathers = one_call_three_days_ago.forecast_hourly
+```