Merge pull request #59 from UniversalSuperBox/docs-no-warnings

cmlccie · web-flow · commit 2dd57ca9c260 · 2018-08-30T09:56:22.000-04:00
Documentation - Fix warnings, add to CI
diff --git a/Makefile b/Makefile
@@ -10,7 +10,7 @@ buildpackage : setup.py
 
 .PHONY : docs
 docs : docs/Makefile
-	cd docs/ && $(MAKE) html
+	cd docs/ && $(MAKE) html SPHINXOPTS="-W"
 
 
 # Local project directory and environment management recipes
@@ -38,8 +38,7 @@ ci-init :
 	pipenv install
 
 .PHONY : ci
-ci :
-	pipenv run pytest -m "not ratelimit"
+ci : pytest docs
 
 .PHONY : toxtest
 toxtest : tox.ini
diff --git a/ciscosparkapi/api/access_tokens.py b/ciscosparkapi/api/access_tokens.py
@@ -96,7 +96,7 @@ def get(self, client_id, client_secret, code, redirect_uri):
 
         Returns:
             ciscosparkapi.AccessToken: An AccessToken object with the access
-                token provided by the Cisco Spark cloud.
+            token provided by the Cisco Spark cloud.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -137,7 +137,7 @@ def refresh(self, client_id, client_secret, refresh_token):
 
         Returns:
             AccessToken: With the access token provided by the Cisco Spark
-                cloud.
+            cloud.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/events.py b/ciscosparkapi/api/events.py
@@ -96,7 +96,7 @@ def list(self, resource=None, type=None, actorId=None, _from=None, to=None,
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the events returned by the Cisco Spark query.
+            yields the events returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/licenses.py b/ciscosparkapi/api/licenses.py
@@ -83,7 +83,7 @@ def list(self, orgId=None, max=None, **request_parameters):
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the licenses returned by the Cisco Spark query.
+            yields the licenses returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -114,7 +114,7 @@ def get(self, licenseId):
 
         Returns:
             License: A License object with the details of the requested
-                License.
+            License.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/memberships.py b/ciscosparkapi/api/memberships.py
@@ -93,7 +93,7 @@ def list(self, roomId=None, personId=None, personEmail=None, max=None,
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the memberships returned by the Cisco Spark query.
+            yields the memberships returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -137,7 +137,7 @@ def create(self, roomId, personId=None, personEmail=None,
 
         Returns:
             Membership: A Membership object with the details of the created
-                membership.
+            membership.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -171,7 +171,7 @@ def get(self, membershipId):
 
         Returns:
             Membership: A Membership object with the details of the requested
-                membership.
+            membership.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -197,7 +197,7 @@ def update(self, membershipId, isModerator=None, **request_parameters):
 
         Returns:
             Membership: A Membership object with the updated Spark membership
-                details.
+            details.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/messages.py b/ciscosparkapi/api/messages.py
@@ -90,7 +90,7 @@ def list(self, roomId, mentionedPeople=None, before=None,
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the messages returned by the Cisco Spark query.
+            yields the messages returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -137,7 +137,7 @@ def create(self, roomId=None, toPersonId=None, toPersonEmail=None,
                 specified this parameter may be optionally used to provide
                 alternate text for UI clients that do not support rich text.
             markdown(basestring): The message, in markdown format.
-            files(list): A list of public URL(s) or local path(s) to files to
+            files(`list`): A list of public URL(s) or local path(s) to files to
                 be posted into the room. Only one file is allowed per message.
                 Uploaded files are automatically converted into a format that
                 all Spark clients can render.
@@ -213,7 +213,7 @@ def get(self, messageId):
 
         Returns:
             Message: A Message object with the details of the requested
-                message.
+            message.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/organizations.py b/ciscosparkapi/api/organizations.py
@@ -79,7 +79,7 @@ def list(self, max=None, **request_parameters):
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the organizations returned by the Cisco Spark query.
+            yields the organizations returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -108,7 +108,7 @@ def get(self, orgId):
 
         Returns:
             Organization: An Organization object with the details of the
-                requested organization.
+            requested organization.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/people.py b/ciscosparkapi/api/people.py
@@ -86,7 +86,7 @@ def list(self, email=None, displayName=None, id=None, orgId=None, max=None,
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the people returned by the Cisco Spark query.
+            yields the people returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -123,16 +123,16 @@ def create(self, emails, displayName=None, firstName=None, lastName=None,
         Only an admin can create a new user account.
 
         Args:
-            emails(list): Email address(es) of the person (list of strings).
+            emails(`list`): Email address(es) of the person (list of strings).
             displayName(basestring): Full name of the person.
             firstName(basestring): First name of the person.
             lastName(basestring): Last name of the person.
             avatar(basestring): URL to the person's avatar in PNG format.
             orgId(basestring): ID of the organization to which this
                 person belongs.
-            roles(list): Roles of the person (list of strings containing
+            roles(`list`): Roles of the person (list of strings containing
                 the role IDs to be assigned to the person).
-            licenses(list): Licenses allocated to the person (list of
+            licenses(`list`): Licenses allocated to the person (list of
                 strings - containing the license IDs to be allocated to the
                 person).
             **request_parameters: Additional request parameters (provides
@@ -211,16 +211,16 @@ def update(self, personId, emails=None, displayName=None, firstName=None,
 
         Args:
             personId(basestring): The person ID.
-            emails(list): Email address(es) of the person (list of strings).
+            emails(`list`): Email address(es) of the person (list of strings).
             displayName(basestring): Full name of the person.
             firstName(basestring): First name of the person.
             lastName(basestring): Last name of the person.
             avatar(basestring): URL to the person's avatar in PNG format.
             orgId(basestring): ID of the organization to which this
                 person belongs.
-            roles(list): Roles of the person (list of strings containing
+            roles(`list`): Roles of the person (list of strings containing
                 the role IDs to be assigned to the person).
-            licenses(list): Licenses allocated to the person (list of
+            licenses(`list`): Licenses allocated to the person (list of
                 strings - containing the license IDs to be allocated to the
                 person).
             **request_parameters: Additional request parameters (provides
diff --git a/ciscosparkapi/api/roles.py b/ciscosparkapi/api/roles.py
@@ -79,7 +79,7 @@ def list(self, max=None, **request_parameters):
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the roles returned by the Cisco Spark query.
+            yields the roles returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/rooms.py b/ciscosparkapi/api/rooms.py
@@ -90,7 +90,7 @@ def list(self, teamId=None, type=None, sortBy=None, max=None,
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the rooms returned by the Cisco Spark query.
+            yields the rooms returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/team_memberships.py b/ciscosparkapi/api/team_memberships.py
@@ -80,7 +80,7 @@ def list(self, teamId, max=None, **request_parameters):
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the team memberships returned by the Cisco Spark query.
+            yields the team memberships returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -121,7 +121,7 @@ def create(self, teamId, personId=None, personEmail=None,
 
         Returns:
             TeamMembership: A TeamMembership object with the details of the
-                created team membership.
+            created team membership.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -155,7 +155,7 @@ def get(self, membershipId):
 
         Returns:
             TeamMembership: A TeamMembership object with the details of the
-                requested team membership.
+            requested team membership.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -181,7 +181,7 @@ def update(self, membershipId, isModerator=None, **request_parameters):
 
         Returns:
             TeamMembership: A TeamMembership object with the updated Spark team
-                membership details.
+            membership details.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/teams.py b/ciscosparkapi/api/teams.py
@@ -79,7 +79,7 @@ def list(self, max=None, **request_parameters):
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the teams returned by the Cisco Spark query.
+            yields the teams returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/ciscosparkapi/api/webhooks.py b/ciscosparkapi/api/webhooks.py
@@ -79,7 +79,7 @@ def list(self, max=None, **request_parameters):
 
         Returns:
             GeneratorContainer: A GeneratorContainer which, when iterated,
-                yields the webhooks returned by the Cisco Spark query.
+            yields the webhooks returned by the Cisco Spark query.
 
         Raises:
             TypeError: If the parameter types are incorrect.
@@ -154,7 +154,7 @@ def get(self, webhookId):
 
         Returns:
             Webhook: A Webhook object with the details of the requested
-                webhook.
+            webhook.
 
         Raises:
             TypeError: If the parameter types are incorrect.
diff --git a/docs/conf.py b/docs/conf.py
@@ -62,7 +62,9 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+    'collapse_navigation': False
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -90,7 +92,7 @@
 # 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,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/docs/index.rst b/docs/index.rst
@@ -54,7 +54,7 @@ What is Cisco Spark?
 --------------------
 
     "Cisco Spark is where all your work lives.  Bring your teams together in a
-     place that makes it easy to keep people and work connected."
+    place that makes it easy to keep people and work connected."
 
 Check out the official `Cisco Spark`_ website for more information and to
 create a free account!
diff --git a/docs/user/api.rst b/docs/user/api.rst
@@ -104,7 +104,7 @@ roles
 .. _events:
 
 events
------
+------
 
 .. autoclass:: ciscosparkapi.api.events.EventsAPI()
 
diff --git a/docs/user/intro.rst b/docs/user/intro.rst
@@ -136,7 +136,7 @@ Head over to the :ref:`Quickstart` page to begin working with the
 **Cisco Spark APIs in native Python**!
 
 
-.. _License:
+.. _MITLicense:
 
 MIT License
 -----------
