Tweak docs

Author: ethantkoenig

docs/examples.rst

@@ -24,7 +24,7 @@ Below is an example illustrating how to retrieve information about a repository:
             print("Repository is not a fork")
 
 
-Example 2: Updating a User
+Example 2: Updating a user
 --------------------------
 
 Below is an example demonstrating how to update a user (requires admin privileges)::
@@ -50,25 +50,13 @@ Below is an example demonstrating how to update a user (requires admin privilege
 Example 3: Creating a token
 ---------------------------
 
-Below is an example illustrating how to create a token for you application::
+Below is an example illustrating how to create a token::
 
     import gogs_client
-    from getpass import getpass
-    from platform import node
 
-    api = GogsApi("https://try.gogs.io/")
-
-    try: token_str = open("tokenfile.txt","r").read()
-    except OSError: token_str = None
-    if token_str:
-        token = gogs_client.Token(token_str)
-    else:
-        username = input("username> ")
-        password = getpass("password> ")
-        login = gogs_client.UsernamePassword(username, password)
-        token = api.ensure_token(login, "my cool app on "+node(), username)
-        open("tokenfile.txt", "w".write(token.token))
+    api = gogs_client.GogsApi("https://try.gogs.io/")
 
-    username = api.authenticated_user(token)
-    print("User {} authenticated by token {}".format(username, token_str))
+    auth = gogs_client.UsernamePassword("username", "password")
+    token = api.create_token(auth, "my_token")
 
+    print("token: {}, name: {}".format(token.token, token.name))

gogs_client/interface.py

@@ -21,7 +21,7 @@ def __init__(self, base_url, session=None):
 
     def valid_authentication(self, auth):
         """
-        Returns whether the provided authentication is valid
+        Returns whether ``auth`` is valid
 
         :param auth.Authentication auth: authentication object
         :return: whether the provided authentication is valid
@@ -32,11 +32,11 @@ def valid_authentication(self, auth):
 
     def authenticated_user(self, auth):
         """
-        Returns the user authenticated by the given authentication
+        Returns the user authenticated by ``auth``
 
         :param auth.Authentication auth: authentication for user to retrieve
 
-        :return: user corresponding to the provided authentication
+        :return: user authenticated by the provided authentication
         :rtype: GogsUser
         :raises NetworkFailure: if there is an error communicating with the server
         :raises ApiFailure: if the request cannot be serviced
@@ -46,14 +46,15 @@ def authenticated_user(self, auth):
 
     def get_tokens(self, auth, username=None):
         """
-        Returns tokens defined for specified user.
-        If no user specified uses user authenticated by the given authentication.
-        Right now, authentication must be UsernamePassword (not Token).
+        Returns the tokens owned by the specified user. If no user is specified,
+        uses the user authenticated by ``auth``.
 
-        :param auth.Authentication auth: authentication for user to retrieve
+        :param auth.Authentication auth: authentication for user to retrieve.
+        Must be a username-password authentication, due to a restriction of the
+        Gogs API
         :param str username: username of owner of tokens
 
-        :return: list of token representation
+        :return: list of tokens
         :rtype: List[Token]
         :raises NetworkFailure: if there is an error communicating with the server
         :raises ApiFailure: if the request cannot be serviced
@@ -65,11 +66,12 @@ def get_tokens(self, auth, username=None):
 
     def create_token(self, auth, name, username=None):
         """
-        Creates new token with specified name for specified user.
-        If no user specified uses user authenticated by the given authentication.
-        Right now, authentication must be UsernamePassword (not Token).
+        Creates a new token with the specified name for the specified user.
+        If no user is specified, uses user authenticated by ``auth``.
 
-        :param auth.Authentication auth: authentication for user to retrieve
+        :param auth.Authentication auth: authentication for user to retrieve.
+        Must be a username-password authentication, due to a restriction of the
+        Gogs API
         :param str name: name of new token
         :param str username: username of owner of new token
 
@@ -86,11 +88,13 @@ def create_token(self, auth, name, username=None):
 
     def ensure_token(self, auth, name, username=None):
         """
-        Creates new token if token with specified name for specified user does not exists.
-        If no user specified uses user authenticated by the given authentication.
-        Right now, authentication must be UsernamePassword (not Token).
+        Ensures the existence of a token with the specified name for the
+        specified user. Creates a new token if none exists. If no user is
+        specified, uses user authenticated by ``auth``.
 
-        :param auth.Authentication auth: authentication for user to retrieve
+        :param auth.Authentication auth: authentication for user to retrieve.
+        Must be a username-password authentication, due to a restriction of the
+        Gogs API
         :param str name: name of new token
         :param str username: username of owner of new token