docs, docs, docs!

Author: csparpa

sphinx/usage-examples-v2/agro-api-usage-examples.md renamed to sphinx/v3/agro-api-usage-examples.md

@@ -21,6 +21,9 @@ Please be aware that also data forecasts can be returned, depending on the searc
 
 Getting the data is easy:
 ```
+from pyowm import OWM
+owm = OWM('apikey')
+
 # Get latest CO Index on geocoordinates
 coi = owm.coindex_around_coords(lat, lon)
 

sphinx/usage-examples-v2/air-pollution-api-usage-examples.md renamed to sphinx/v3/air-pollution-api-usage-examples.md

@@ -22,7 +22,7 @@ from pyowm.alertapi30.enums import WeatherParametersEnum, OperatorsEnum, AlertCh
 from pyowm.alertapi30.condition import Condition
 
 # obtain an AlertManager instance
-owm = OWM(API_Key='blablabla')
+owm = OWM('apikey')
 am = owm.alert_manager()
 
 # -- areas --

sphinx/usage-examples-v2/alerts-api-usage-examples.md renamed to sphinx/v3/alerts-api-usage-examples.md

@@ -0,0 +1,7 @@
+# City ID Registry usage examples
+
+Using city IDS instead of toponyms or geographic coordinates is the preferred way of querying the OWM weather API
+ 
+You can obtain the city ID for your toponyms/geoocoords of interest via the `City ID Registry`.
+
+Please refer to the `Code Recipes` page, section: `Identifying cities and places via city IDs`, to get info about it

sphinx/v3/city-id-registry-examples.md

@@ -0,0 +1,46 @@
+# Exceptions
+
+PyOWM uses custom exception classes. Here you can learn which classes are used and when such exceptions are cast by the library
+
+## Exceptions Hierarchy
+
+```
+Exception
+|
+|___PyOWMError
+    |
+    |___ConfigurationError
+    |   |
+    |   |__ConfigurationNotFoundError
+    |   |__ConfigurationParseError
+    |
+    |___APIRequestError
+    |   |
+    |   |__BadGatewayError
+    |   |__TimeoutError
+    |   |__InvalidSSLCertificateError
+    |
+    |___APIResponseError
+        |
+        |__NotFoundError
+        |__UnauthorizedError
+        |__ParseAPIResponseError
+```
+
+## Exception root causes
+
+  * `PyOWMError` is the base class. Never raised directly
+  * `ConfigurationError` parent class for configuration-related exceptions. Never raised directly
+  * `ConfigurationNotFoundError` raised when trying to load configuration from a non-existent file
+  * `ConfigurationParseError` raised when configuration can be loaded from the file but is in a wrong, unparsable format
+  * `APIRequestError` base class for network/infrastructural issues when invoking OWM APIs
+  * `BadGatewayError` raised when upstream OWM API backends suffer communication issues.
+  * `TimeoutError` raised when calls to the API suffer timeout due to slow response times upstream
+  * `InvalidSSLCertificateError` raised when it is impossible to verify the SSL certificates provided by the OWM APIs  
+  * `APIResponseError` base class for non-ok API responses from OWM APIs
+  * `NotFoundError` raised when the user tries to access resources that do not exist on the OWM APIs
+  * `UnauthorizedError` raised when the user tries to access resources she is not authorized to access (eg. you need a paid API subscription)
+  * `ParseAPIResponseError` raised upon impossibility to parse the JSON payload of API responses
+
+
+

sphinx/v3/exceptions.md

@@ -0,0 +1,31 @@
+# Global PyOWM library usage examples
+
+The PyOWM library has one main entry point: the `OWM` class. You just need to instantiate it to get started!
+
+Please refer to the `Code Recipes` page, section: `Library initialization`, to get info about how to instantiate 
+the PyOWM library
+
+
+
+## Dumping PyOWM objects to Python dictionaries
+PyOWM object instances (eg. `Weather` or `Location` objects) can be dumped to `dict`s:
+
+```python
+from pyowm.owm import OWM
+owm = OWM('your-api-key')
+mgr = owm.weather_manager()
+weather = mgr.weather_at_place('London,GB').weather  # get the weather at London,GB now
+dump_dict = weather.to_dict()
+```
+
+This is useful as you can save the dump dictionaries to files (eg. using Pyhon `json` or `pickle` modules)
+
+## Printing objects
+Most of PyOWM objects can be pretty-printed for a quick introspection:
+
+```python
+from pyowm.owm import OWM
+owm = OWM('your-api-key')
+print(owm)   # <pyowm.weatherapi25.owm25.OWM25 - API key=*******i-key, subscription type=free, PyOWM version=3.0.0>
+```
+

sphinx/v3/global-pyowm-usage-examples.md

@@ -0,0 +1,73 @@
+# PyOWM configuration description
+
+PyOWM can be configured at your convenience.
+
+The library comes with a pre-cooked configuration that you can change according to your needs. The configuration is formulated as a Python dictionary.
+
+## Default configuration
+The default config is the `DEFAULT_CONFIG` dict living in the `pyowm.config` module (check it to know the defaults) 
+
+## Configuration format
+The config dict is formatted as follows:
+
+```
+{
+    "subscription_type": <pyowm.commons.enums.SubscriptionTypeEnum>,
+    "language": <str>,
+    "connection": {
+        "use_ssl": <bool>
+        "verify_ssl_certs": <bool>>,
+        "use_proxy": <bool>,
+        "timeout_secs": <int>
+    },
+    "proxies": {
+        "http": <str>,
+        "https": <str>
+    }
+}
+```
+
+Here are the keys:
+
+  * `subscription_type`: this object represents an OWM API Plan subscription. Possible values are: `free|startup|developer|professional|enterprise`
+  * `language`: 2-char string representing the language you want the weather statuses returned in. Currently serving: `en|ru|ar|zh_cn|ja|es|it|fr|de|pt` and more. Check [here](https://openweathermap.org/current) for a comprehensive list of supported languages
+  * `connection`:
+    * `use_ssl`: whether to use SSL or not for API calls
+    * `verify_ssl_certs`: speaks by itself..
+    * `use_proxy`: whether to use a proxy server or not (useful if you're eg. in a corporate network). HTTP and SOCKS5 proxies are allowed
+    * `timeout_secs`: after how many seconds the API calls should be timeouted
+  * `proxies` (this sub-dict is ignored if `use_proxy == False`)
+    * `http`: the HTTP URL of the proxy server
+    * `https`: the HTTPS/SOCKS5 URL of the proxy server
+
+## Providing a custom configuration
+You can either pass in your custom dict to the global `OWM` object upon instantiation:
+
+```python
+from pyowm import OWM
+owm = OWM('my-api-key', config=my_custom_config_dict)  # pass in your dict as a named argument
+```
+
+or you can put your custom configuration inside a JSON text file and have it read by PyOWM:
+
+```python
+from pyowm.owm import OWM
+from pyowm.utils.config import get_config_from
+config_dict = get_config_from('/path/to/configfile.json')  # This utility comes in handy
+owm = OWM('your-free-api-key', config_dict)
+```
+
+Be aware that the JSON file must be properly formatted and that the unspecified non-mandatory keys will be filled in with default values. Here is an example:
+
+```json
+{
+    "api_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+    "subscription_type": "professional",
+    "language": "ru",
+    "connection": {
+        "use_ssl": true,
+        "verify_ssl_certs": true,
+        "timeout_secs": 1
+    }
+}
+```

sphinx/usage-examples-v2/map-tiles-client-examples.md renamed to sphinx/v3/map-tiles-client-usage-examples.md

@@ -9,7 +9,10 @@ Please refer to the official API docs for [UV](http://openweathermap.org/api/uvi
 Getting the data is easy:
 
 ```python
-uvi = owm.uvindex_around_coords(lat, lon)
+from pyowm import OWM
+owm = OWM('apikey')
+mgr = owm.uvindex_manager()
+uvi = mgr.uvindex_around_coords(lat, lon)
 ```
 
 The query returns an UV Index value entity instance
@@ -20,15 +23,15 @@ The query returns an UV Index value entity instance
 As easy as:
 
 ```python
-uvi_list = owm.uvindex_forecast_around_coords(lat, lon)
+uvi_list = mgr.uvindex_forecast_around_coords(lat, lon)
 ```
 
 ### Querying UV index history
 
 As easy as: 
 
 ```python
-uvi_history_list = owm.uvindex_history_around_coords(
+uvi_history_list = mgr.uvindex_history_around_coords(
     lat, lon,
     datetime.datetime(2017, 8, 1, 0, 0),
     end=datetime.datetime(2018, 2, 15, 0, 0))