Update docs

- Change Spark references to Webex Teams
- Change location and instructions for obtaining a Personal Access Token
- Simplify the methods-list table in the Quickstart
- Add MalformedResponse and RateLimitWarning to the top-level package interface
- Change autodoc_default_flags (deprecated) to autodoc_default_options

Author: cmlccie

docs/conf.py

@@ -36,9 +36,13 @@
 pygments_style = 'sphinx'
 
 
-
-autodoc_member_order = 'bysource'
-autodoc_default_flags = ['members', 'undoc-members']
+# autodoc_member_order = 'bysource'
+# autodoc_default_flags = ['members', 'undoc-members']
+autodoc_default_options = {
+    'member-order': 'bysource',
+    'members': None,
+    'undoc-members': None,
+}
 
 
 todo_include_todos = True

docs/images/_originals/spark_access_token.png

@@ -10,8 +10,8 @@ webexteamssdk
 
 Welcome to the docs!  webexteamssdk is a *community developed* Pythonic
 wrapping of the Webex Teams APIs.  The package represents all of the Cisco
-Spark API interactions via native Python tools.  Making working with the Cisco
-Spark APIs in Python a *native* and *natural* experience.
+Webex Teams API interactions via native Python tools.  Making working with the Cisco
+Webex Teams APIs in Python a *native* and *natural* experience.
 
 **webexteamssdk helps you get things done faster.**  We take
 care of the API semantics, and you can focus on writing your code.
@@ -20,10 +20,10 @@ With webexteamssdk, you can easily:
 
 * Interact with the Webex Teams APIs in an interactive Python session
 
-* Quickly create code that enables you get something done in Spark
+* Quickly create code that enables you get something done in Webex Teams
 
-* Leverage the API wrapper to cleanly add Spark functionality to your project
-  without having to write the boilerplate code for working with the Spark APIs
+* Leverage the API wrapper to cleanly add Webex Teams functionality to your project
+  without having to write the boilerplate code for working with the Webex Teams APIs
 
 To *dive in* and see how webexteamssdk makes your life better, check out the
 :ref:`Quickstart`!
@@ -59,19 +59,19 @@ What is Webex Teams?
 Check out the official `Webex Teams`_ website for more information and to
 create a free account!
 
-Spark for Developers
---------------------
+Webex Teams for Developers
+--------------------------
 
 Leveraging the Webex Teams APIs and developing on top of the Webex Teams cloud
 is easy.  Signup for a `free account`_ and then head over to the
-`Spark for Developers`_ website to learn more.
+`Webex Teams for Developers`_ website to learn more.
 
 
 *Copyright (c) 2016-2018 Cisco and/or its affiliates.*
 
 
 .. _free account: `Webex Teams`
-.. _Webex Teams: https://www.ciscospark.com/
-.. _Spark for Developers: https://developer.ciscospark.com/
+.. _Webex Teams: https://www.webex.com/products/teams/index.html
+.. _Webex Teams for Developers: https://developer.webex.com/
 .. _contribution: https://github.com/CiscoDevNet/webexteamssdk#contribution
 .. _webexteamssdk: https://github.com/CiscoDevNet/webexteamssdk

docs/images/personal_access_token.png

@@ -7,18 +7,18 @@ User API Doc
 ============
 
 
-CiscoSparkAPI
+WebexTeamsAPI
 =============
 
-The :class:`CiscoSparkAPI` class is the main interface for the package. All of
-the Spark APIs (people, rooms, etc.) and their API endpoints have been wrapped
-and hierarchically organized underneath the :class:`CiscoSparkAPI` class.
+The :class:`WebexTeamsAPI` class is the main interface for the package. All of
+the Webex Teams APIs (people, rooms, etc.) and their API endpoints have been wrapped
+and hierarchically organized underneath the :class:`WebexTeamsAPI` class.
 
-.. autoclass:: CiscoSparkAPI()
+.. autoclass:: WebexTeamsAPI()
     :members:
     :exclude-members: access_token, base_url, timeout
 
-    .. automethod:: CiscoSparkAPI.__init__
+    .. automethod:: WebexTeamsAPI.__init__
 
 
 .. _people:
@@ -117,28 +117,10 @@ access_tokens
 .. autoclass:: webexteamssdk.api.access_tokens.AccessTokensAPI()
 
 
-.. _Exceptions:
-
-Exceptions
-==========
-
-.. autoexception:: webexteamssdkException()
-    :show-inheritance:
-    :members:
-
-.. autoexception:: ApiError()
-    :show-inheritance:
-    :members:
+.. _Webex Teams Data Objects:
 
-.. autoexception:: RateLimitError()
-    :show-inheritance:
-    :members:
-
-
-.. _Spark Data Objects:
-
-Spark Data Objects
-==================
+Webex Teams Data Objects
+========================
 
 
 .. _Person:
@@ -258,4 +240,40 @@ Access Token
     :inherited-members:
 
 
+.. _Exceptions:
+
+Exceptions
+==========
+
+.. autoexception:: webexteamssdkException()
+    :show-inheritance:
+    :members:
+
+.. autoexception:: AccessTokenError()
+    :show-inheritance:
+    :members:
+
+.. autoexception:: ApiError()
+    :show-inheritance:
+    :members:
+
+.. autoexception:: MalformedResponse()
+    :show-inheritance:
+    :members:
+
+.. autoexception:: RateLimitError()
+    :show-inheritance:
+    :members:
+
+
+.. _Warnings:
+
+Warnings
+========
+
+.. autoexception:: RateLimitWarning()
+    :show-inheritance:
+    :members:
+
+
 *Copyright (c) 2016-2018 Cisco and/or its affiliates.*

docs/images/spark_access_token.png

@@ -9,7 +9,7 @@ Work with the Webex Teams APIs in Native Python!
 ------------------------------------------------
 
 Sure, working with the Webex Teams APIs is easy (see
-`developer.ciscospark.com`_).  They are RESTful,  naturally structured,
+`developer.webex.com`_).  They are RESTful,  naturally structured,
 require only a simple Access Token for authentication, and the data is
 elegantly represented in intuitive JSON.  What could be easier?
 
@@ -47,16 +47,16 @@ Like I said, EASY.  However, in use, the code can become rather repetitive...
 - When requesting lists of items, you have to deal with pagination_
 
 
-Enter **webexteamssdk**, a simple API wrapper that wraps all of the Spark API
+Enter **webexteamssdk**, a simple API wrapper that wraps all of the Webex Teams API
 calls and returned JSON objects within native Python objects and methods.
 
 With webexteamssdk, the above Python code can be consolidated to the following:
 
 .. code-block:: python
 
-    from webexteamssdk import CiscoSparkAPI
+    from webexteamssdk import WebexTeamsAPI
 
-    api = CiscoSparkAPI()
+    api = WebexTeamsAPI()
     try:
         message = api.messages.create('<room_id>', text='<message_text>')
         print("New message created, with ID:", message.id)
@@ -67,10 +67,10 @@ With webexteamssdk, the above Python code can be consolidated to the following:
 
 **webexteamssdk handles all of this for you:**
 
-+ Reads your Spark access token from a ``SPARK_ACCESS_TOKEN`` environment
++ Reads your Webex Teams access token from a ``WEBEX_TEAMS_ACCESS_TOKEN`` environment
   variable
 
-+ Wraps and represents all Spark API calls as a simple hierarchical tree of
++ Wraps and represents all Webex Teams API calls as a simple hierarchical tree of
   native-Python methods (with default arguments provided everywhere possible!)
 
 + If your Python IDE supports **auto-completion** (like PyCharm_), you can
@@ -80,14 +80,14 @@ With webexteamssdk, the above Python code can be consolidated to the following:
   access all of the object's attributes using native *dot.syntax*
 
 + **Automatic and Transparent Pagination!**  When requesting 'lists of objects'
-  from Spark, requests for additional pages of responses are efficiently and
+  from Webex Teams, requests for additional pages of responses are efficiently and
   automatically requested as needed
 
 + **Automatic Rate-Limit Handling**  Sending a lot of requests to Webex Teams?
-  Don't worry; we have you covered.  Spark will respond with a rate-limit
+  Don't worry; we have you covered.  Webex Teams will respond with a rate-limit
   response, which will automatically be caught and "handled" for you.  Your
   requests and script will automatically be "paused" for the amount of time
-  specified by Spark, while we wait for the Spark rate-limit timer to cool
+  specified by Webex Teams, while we wait for the Webex Teams rate-limit timer to cool
   down.  After the cool-down, your request will automatically be retried, and
   your script will continue to run as normal.  Handling all of this requires
   zero (0) changes to your code - you're welcome.  😎
@@ -103,9 +103,9 @@ All of this, combined, lets you do powerful things simply:
 
 .. code-block:: python
 
-    from webexteamssdk import CiscoSparkAPI
+    from webexteamssdk import WebexTeamsAPI
 
-    api = CiscoSparkAPI()
+    api = WebexTeamsAPI()
 
     # Find all rooms that have 'webexteamssdk Demo' in their title
     all_rooms = api.rooms.list()
@@ -125,10 +125,10 @@ All of this, combined, lets you do powerful things simply:
 
     # Post a message to the new room, and upload a file
     api.messages.create(demo_room.id, text="Welcome to the room!",
-                        files=["https://developer.ciscospark.com/images/logo_spark_lg@256.png"])
+                        files=["https://www.webex.com/content/dam/wbx/us/images/dg-integ/teams_icon.png"])
 
 
-That's more than 6 Spark API calls in less than 23 lines of code (with comments
+That's more than 6 Webex Teams API calls in less than 23 lines of code (with comments
 and whitespace), and likely more than that since webexteamssdk handles
 pagination_ for you automatically!
 
@@ -155,7 +155,7 @@ webexteamssdk License
 
 
 .. _MIT Open Source License: https://opensource.org/licenses/MIT
-.. _developer.ciscospark.com: https://developer.ciscospark.com
-.. _pagination: https://developer.ciscospark.com/pagination.html
+.. _developer.webex.com: https://developer.webex.com
+.. _pagination: https://developer.webex.com/pagination.html
 .. _PyCharm: https://www.jetbrains.com/pycharm/