Refactoring/Restructuring for readability + Added Examples

Development_API.md

@@ -1,7 +1,7 @@
 # Development API
-Apprise is very easy to use as a developer. The Apprise() object handles everything for you, meanwhile the AppriseAsset() Object allows you to stray away from some default configuration to personalize the users experience (and perhaps fit your application better):
+Apprise is very easy to use as a developer. The **Apprise()** object handles everything for you, meanwhile the **AppriseAsset()** Object allows you to stray away from some default configuration to personalize the users experience (and perhaps fit your application better):
-* [[The Apprise Object|Development_API#the-apprise-object]]
+* **[[The Apprise Object|Development_API#the-apprise-object]]**
-* [[The Apprise Asset Object|Development_API#the-apprise-asset-object]]
+* **[[The Apprise Asset Object|Development_API#the-apprise-asset-object]]**
 
 ## The Apprise Object
 The Apprise() object is the heart and soul of this library. To instantiate an instance of the object, one might do the following:
@@ -13,6 +13,7 @@ import apprise
 apobj = apprise.Apprise()
 ```
 
+### add(): Add a New Notification Service By URL(s)
 Use the **add()** function to append the notification URLs we want to provide notifications for.
 ```python
 # Add all of the notification services by their server url.
@@ -24,16 +25,41 @@ isokay = apobj.add('mailto://myemail:mypass@gmail.com')
 
 # A sample pushbullet notification
 isokay = apobj.add('pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b')
+
+# You can additionally add URLs via a list/set/tuple:
+isokay = apobj.add([
+   # A sample growl service
+   'growl://192.168.40.23',
+
+   # Our Microsoft Windows desktop
+   'windows://',
+])
 ```
 
-We can retrieve a list of the active and loaded notification services by using python's built in
+#### Tagging
-**len()** function.
+Tagging is a great way to add a richer experience to the notification flow.
+You can associate one or more _tags_ with the notifications you choose to **add()**. Doing so grants you to flexibility to later call _on just some_ (_or all_) of the services you added. It effectively grants you the additional ability to filter notifications based on your workflow.
+
+Here is an example:
 ```python
-# len(apobj) returns the number of notifications loaded
+# import our library
-# the below calls this and prints it to the screen:
+import apprise
-print("There are %d notification services loaded" % len(apobj))
+
+# Create our object
+apobj = apprise.Apprise()
+
+# Add a tag by a simple string
+apobj.add('json://localhost/tagA/', tag="TagA")
+
+# Add 2 tags by string; the comma and/or space auto delimit
+# our entries (spaces and comma's are ignored):
+apobj.add('json://localhost/tagAB/', tag="TagA, TagB")
+
+# Add 2 tags using a list; this works with tuples and sets too!
+apobj.add('json://localhost/tagCD/', tag=["TagC", "TagD"])
 ```
 
+### notify() : Send Notification(s)
 You can now send a notification to all of the loaded notifications services by just providing it a **title** and a **body** like so:
 ```python
 # Then notify these services any time you desire. The below would
@@ -42,96 +68,71 @@ apobj.notify(
     title='my notification title',
     body='what a great notification service!',
 )
+```
+#### Leverage Tagging
+If you associated tags with your notification services (when you called **add()** earlier, you can leverage it's full potential through the **notify()** function here. Tagging however allows you to trigger notifications only when a criteria is met. The tagging logic can be interpreted as follows:
 
+| apprise.notify(tag=**match**)  | Tag Representation       |
+| -------------------------------- | ------------------------ |
+| _None_                           |  All Notifications (_this is the default_)
+| "TagA"                           |  TagA
+| "TagA, TagB"                     |  TagA **OR** TagB
+| ['TagA', 'TagB']                 |  TagA **OR** TagB
+| [('TagA', 'TagC'), 'TagB']       |  (TagA **AND** TagC) **OR** TagB
+| [('TagB', 'TagC')]               |  TagB **AND** TagC
+
+Now that we've added our services and assigned them tags, this is how we can access them:
+```python
+# Has TagA
+apobj.notify(title='a title', body="a body",  tag="tagA")
+
+# Has TagA OR TagB
+apobj.notify(title='a title', body="a body", tag=["tagA", "TagB"])
+
+# Has TagA AND TagB
+apobj.notify(title='a title', body="a body", tag=[("tagA", "TagB")])
+
+# Has TagA OR TagB OR (TagC AND TagD)
+apobj.notify(title='a title', body="a body", tag=["tagA", "TagB", ["TagC", "TagD"]])
+
+# No reference to tags; alert all of the added services
+apobj.notify(title="my title", body="my body")
 ```
 
-Tagging is a great way to add a richer experience to the notification flow.
+### Tagging and Categories
-You can associate one or more _tags_ with the notifications you choose to add. This grants you to flexibility to later call on just some (or all) of your added services. It also allows you to easily filter out notifications based on user preferences.
+Another example would be a system owner filling their code with clean logic like:
+```python
+#...
+apobj.notify(title='a title', body="a body", tag="service-message")
+# ...
+apobj.notify(title='a title', body="a body", tag="debug-message")
+# ...
+apobj.notify(title='a title', body="a body", tag="broadcast-notice")
+# ...
+```
 
-Here is an example:
+Then somewhere when the Apprise Object (_apobj_) is first created, you poll your user for their settings and only load what they're interested in:
 ```python
 # import our library
 import apprise
 
 # Create our object
-a = apprise.Apprise()
+apobj = apprise.Apprise()
 
-# Add a tag by tuple
+# Poll our user for their setting and add them
-a.add('json://localhost/tagA/', tag=("TagA", ))
+apobj.add('mailto://myuser:theirpassword@hotmail.com', tag=[
+   # Services we want to subscribe to
+   "service-message",
+   "broadcast-notice"
+])
 
-# Add 2 tags by string; the comma and/or space auto delimit
+# Note that in this example, the user would never be notified for
-# our entries
+# "debug-message" calls. Yet the system owner does not need to provide
-a.add('json://localhost/tagAB/', tag="TagA, TagB")
+# any additional logic around this call to perform this filter since
-
+# apprise will take care of it for you.
-# Add a tag using a set
-a.add('json://localhost/tagB/', tag=set(["TagB"])
-
-# Add a tag by string (again)
-a.add('json://localhost/tagC/', tag="TagC")
-
-# Add 2 tags using a list
-a.add('json://localhost/tagCD/', tag=["TagC", "TagD"])
-
-# Add a tag by string (again)
-a.add('json://localhost/tagD/', tag="TagD")
-
-# add a tag set by set (again)
-a.add('json://localhost/tagCDE/', tag=set(["TagC", "TagD", "TagE"]))
 ```
 
-Now that we've added our services and assigned them tags, this is how we can access them:
+#### Message Types and Themes
-```python
-# Notify services associated with tag: TagA
-# Matches the following only:
-#   - json://localhost/tagA/
-#   - json://localhost/tagAB/
-a.notify(title="my title", body="my body", tag='TagA')
-
-# Notify services associated with tag: TagA OR TagB
-# Matches the following only:
-#   - json://localhost/tagA/
-#   - json://localhost/tagAB/
-#   - json://localhost/tagB/
-a.notify(title="my title", body="my body", tag=['TagA', 'TagB'])
-
-# The AND requires you nest an additional list/tuple/set inside
-# your tag list...
-
-# Notify services associated with tags: TagC AND TagD
-# Matches the following only:
-#   - json://localhost/tagCD/
-#   - json://localhost/tagCDE/
-a.notify(title="my title", body="my body", tag=[('TagC', 'TagD')])
-
-# Notify services associated with tags: (TagY AND TagZ) OR TagX
-# Matches nothing
-a.notify(title="my title", body="my body", tag=[('TagY', 'TagZ'), 'TagX'])
-
-# Notify services associated with tags: (TagY AND TagZ) OR TagA
-# Matches the following only:
-#   - json://localhost/tagAB/
-a.notify(title="my title", body="my body", tag=[('TagY', 'TagZ'), 'TagA'])
-
-# Notify services associated with tags: (TagE AND TagD) OR TagB
-# Matches the following only:
-#   - json://localhost/tagCDE/
-#   - json://localhost/tagAB/
-#   - json://localhost/tagB/
-a.notify(title="my title", body="my body", tag=[('TagE', 'TagD'), 'TagB'])
-
-# Expression: None
-# Matches every single service.
-a.notify(title="my title", body="my body")
-```
-You could look at the **apprise.notify()** logic like this:
-
-| tag=                      | Tag Representation       |
-| ------------------------- | ------------------------ |
-| "TagA, TagB"              |  TagA **OR** TagB
-| ['TagA', 'TagB']          |  TagA **OR** TagB
-| [('TagA', 'TagC'), 'TagB']|  (TagA **AND** TagC) **OR** TagB
-| [('TagB', 'TagC')]        |  TagB **AND** TagC
-
 By default, all notifications are sent as type **NotifyType.INFO** using the _default_ theme. The following other types are included with this theme:
 
 | Notification Type    | Text Representation | Image |
@@ -155,14 +156,26 @@ apobj.notify(
 )
 ```
 
-If you ever want to reset the object, you can use the **clear()** function.
+You can alter the theme as well; this is discussed lower down using the [[the Apprise Asset Object|Development_API#the-apprise-asset-object]].
+
+### len(): Returns Number of Notification Services loaded
+
+We can retrieve a list of the active and loaded notification services by using python's built in
+**len()** function.
+```python
+# len(apobj) returns the number of notifications loaded
+# the below calls this and prints it to the screen:
+print("There are %d notification services loaded" % len(apobj))
+```
+### clear(): Reset our Apprise Object
+If you ever want to reset our Apprise object, and eliminate all of the services we had previously loaded into it, you can use the **clear()** function.
 ```python
 # clears out all of the loaded notification services associated with our
 # Apprise Object.
 apobj.clear()
 ```
-
+### details(): Dynamic View Into Available Notification Services Apprise Offers
-Developers who wish to be able to generate information based on this library dynamically can use the __details()__ function:
+Developers who wish to be able to generate information based on this library dynamically can use the *details()** function:
 ```python
 # returns an object containing details about the plugin for dynamic integration.
 apobj.details()
@@ -216,14 +229,14 @@ The output will look like:
     ]
 }
 ```
-The idea behind the __details()__ function is that it allows developers to pass details back through their program letting their users know what notifications are supported. Thus as this library deprecates and introduces new notification services, calling front end applications (built around the __details()__ function) can automatically serve this information back to their user base.
+The idea behind the **details()** function is that it allows developers to pass details back through their program letting their users know what notifications are supported. Thus as this library deprecates and introduces new notification services, calling front end applications (built around the **details()** function) can automatically serve this information back to their user base.
 
 ## The Apprise Asset Object
 The apprise object allows you to customize your alarms by offering it different images, different sources and different themes. Different notification services support different ways of passing images into it (and some don't support images at all).  Apprise offers a way of supporting both local and hosted images and looks after passing the correct one to the correct service (when requested).
 
 Even when you're just using the **Apprise()** object, behind the scenes a generic **AppriseAsset()** object is created which retrieves all of it's information from this path: https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default (which is the _default_ theme directory).
 
-A default AppriseAsset() object might have the following defined in it:
+A default **AppriseAsset()** object might have the following defined in it:
 
 | Variable | Default | Type   | Description |
 | -------- | ------- | ------ | ----------- |