docs: add docstrings to auth objects and endpoints (#1484)

* docs: add docstrings to auth objects and endpoints

* docs: add parameters and examples to methods

---------

Co-authored-by: Jordan Woods <13803242+jorwoods@users.noreply.github.com>

tableauserverclient/models/tableau_auth.py

@@ -32,6 +32,43 @@ def deprecate_site_attribute():
 
 # The traditional auth type: username/password
 class TableauAuth(Credentials):
+    """
+    The TableauAuth class defines the information you can set in a sign-in
+    request. The class members correspond to the attributes of a server request
+    or response payload. To use this class, create a new instance, supplying
+    user name, password, and site information if necessary, and pass the
+    request object to the Auth.sign_in method.
+
+    Parameters
+    ----------
+    username : str
+        The user name for the sign-in request.
+
+    password : str
+        The password for the sign-in request.
+
+    site_id : str, optional
+        This corresponds to the contentUrl attribute in the Tableau REST API.
+        The site_id is the portion of the URL that follows the /site/ in the
+        URL. For example, "MarketingTeam" is the site_id in the following URL
+        MyServer/#/site/MarketingTeam/projects. To specify the default site on
+        Tableau Server, you can use an empty string '' (single quotes, no
+        space). For Tableau Cloud, you must provide a value for the site_id.
+
+    user_id_to_impersonate : str, optional
+        Specifies the id (not the name) of the user to sign in as. This is not
+        available for Tableau Online.
+
+    Examples
+    --------
+    >>> import tableauserverclient as TSC
+
+    >>> tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', site_id='CONTENTURL')
+    >>> server = TSC.Server('https://SERVER_URL', use_server_version=True)
+    >>> server.auth.sign_in(tableau_auth)
+
+    """
+
     def __init__(
         self, username: str, password: str, site_id: Optional[str] = None, user_id_to_impersonate: Optional[str] = None
     ) -> None:
@@ -55,6 +92,43 @@ def __repr__(self):
 
 # A Tableau-generated Personal Access Token
 class PersonalAccessTokenAuth(Credentials):
+    """
+    The PersonalAccessTokenAuth class defines the information you can set in a sign-in
+    request. The class members correspond to the attributes of a server request
+    or response payload. To use this class, create a new instance, supplying
+    token name, token secret, and site information if necessary, and pass the
+    request object to the Auth.sign_in method.
+
+    Parameters
+    ----------
+    token_name : str
+        The name of the personal access token.
+
+    personal_access_token : str
+        The personal access token secret for the sign in request.
+
+    site_id : str, optional
+        This corresponds to the contentUrl attribute in the Tableau REST API.
+        The site_id is the portion of the URL that follows the /site/ in the
+        URL. For example, "MarketingTeam" is the site_id in the following URL
+        MyServer/#/site/MarketingTeam/projects. To specify the default site on
+        Tableau Server, you can use an empty string '' (single quotes, no
+        space). For Tableau Cloud, you must provide a value for the site_id.
+
+    user_id_to_impersonate : str, optional
+        Specifies the id (not the name) of the user to sign in as. This is not
+        available for Tableau Online.
+
+    Examples
+    --------
+    >>> import tableauserverclient as TSC
+
+    >>> tableau_auth = TSC.PersonalAccessTokenAuth("token_name", "token_secret", site_id='CONTENTURL')
+    >>> server = TSC.Server('https://SERVER_URL', use_server_version=True)
+    >>> server.auth.sign_in(tableau_auth)
+
+    """
+
     def __init__(
         self,
         token_name: str,
@@ -88,6 +162,42 @@ def __repr__(self):
 
 # A standard JWT generated specifically for Tableau
 class JWTAuth(Credentials):
+    """
+    The JWTAuth class defines the information you can set in a sign-in
+    request. The class members correspond to the attributes of a server request
+    or response payload. To use this class, create a new instance, supplying
+    an encoded JSON Web Token, and site information if necessary, and pass the
+    request object to the Auth.sign_in method.
+
+    Parameters
+    ----------
+    token : str
+        The encoded JSON Web Token.
+
+    site_id : str, optional
+        This corresponds to the contentUrl attribute in the Tableau REST API.
+        The site_id is the portion of the URL that follows the /site/ in the
+        URL. For example, "MarketingTeam" is the site_id in the following URL
+        MyServer/#/site/MarketingTeam/projects. To specify the default site on
+        Tableau Server, you can use an empty string '' (single quotes, no
+        space). For Tableau Cloud, you must provide a value for the site_id.
+
+    user_id_to_impersonate : str, optional
+        Specifies the id (not the name) of the user to sign in as. This is not
+        available for Tableau Online.
+
+    Examples
+    --------
+    >>> import jwt
+    >>> import tableauserverclient as TSC
+
+    >>> jwt_token = jwt.encode(...)
+    >>> tableau_auth = TSC.JWTAuth(token, site_id='CONTENTURL')
+    >>> server = TSC.Server('https://SERVER_URL', use_server_version=True)
+    >>> server.auth.sign_in(tableau_auth)
+
+    """
+
     def __init__(self, jwt: str, site_id: Optional[str] = None, user_id_to_impersonate: Optional[str] = None) -> None:
         if jwt is None:
             raise TabError("Must provide a JWT token when using JWT authentication")

tableauserverclient/server/endpoint/auth_endpoint.py

@@ -41,6 +41,30 @@ def sign_in(self, auth_req: "Credentials") -> contextmgr:
         optionally a user_id to impersonate.
 
         Creates a context manager that will sign out of the server upon exit.
+
+        Parameters
+        ----------
+        auth_req : Credentials
+            The credentials object to use for signing in. Can be a TableauAuth,
+            PersonalAccessTokenAuth, or JWTAuth object.
+
+        Returns
+        -------
+        contextmgr
+            A context manager that will sign out of the server upon exit.
+
+        Examples
+        --------
+        >>> import tableauserverclient as TSC
+
+        >>> # create an auth object
+        >>> tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD')
+
+        >>> # create an instance for your server
+        >>> server = TSC.Server('https://SERVER_URL')
+
+        >>> # call the sign-in method with the auth object
+        >>> server.auth.sign_in(tableau_auth)
         """
         url = f"{self.baseurl}/signin"
         signin_req = RequestFactory.Auth.signin_req(auth_req)
@@ -70,14 +94,17 @@ def sign_in(self, auth_req: "Credentials") -> contextmgr:
     # The distinct methods are mostly useful for explicitly showing api version support for each auth type
     @api(version="3.6")
     def sign_in_with_personal_access_token(self, auth_req: "Credentials") -> contextmgr:
+        """Passthrough to sign_in method"""
         return self.sign_in(auth_req)
 
     @api(version="3.17")
     def sign_in_with_json_web_token(self, auth_req: "Credentials") -> contextmgr:
+        """Passthrough to sign_in method"""
         return self.sign_in(auth_req)
 
     @api(version="2.0")
     def sign_out(self) -> None:
+        """Sign out of current session."""
         url = f"{self.baseurl}/signout"
         # If there are no auth tokens you're already signed out. No-op
         if not self.parent_srv.is_signed_in():
@@ -88,6 +115,33 @@ def sign_out(self) -> None:
 
     @api(version="2.6")
     def switch_site(self, site_item: "SiteItem") -> contextmgr:
+        """
+        Switch to a different site on the server. This will sign out of the
+        current site and sign in to the new site. If used as a context manager,
+        will sign out of the new site upon exit.
+
+        Parameters
+        ----------
+        site_item : SiteItem
+            The site to switch to.
+
+        Returns
+        -------
+        contextmgr
+            A context manager that will sign out of the new site upon exit.
+
+        Examples
+        --------
+        >>> import tableauserverclient as TSC
+
+        >>> # Find the site you want to switch to
+        >>> new_site = server.sites.get_by_id("9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d")
+        >>> # switch to the new site
+        >>> with server.auth.switch_site(new_site):
+        >>>     # do something on the new site
+        >>>     pass
+
+        """
         url = f"{self.baseurl}/switchSite"
         switch_req = RequestFactory.Auth.switch_req(site_item.content_url)
         try:
@@ -109,6 +163,9 @@ def switch_site(self, site_item: "SiteItem") -> contextmgr:
 
     @api(version="3.10")
     def revoke_all_server_admin_tokens(self) -> None:
+        """
+        Revokes all personal access tokens for all server admins on the server.
+        """
         url = f"{self.baseurl}/revokeAllServerAdminTokens"
         self.post_request(url, "")
         logger.info("Revoked all tokens for all server admins")