Doc updates including new page for troubleshooting

_includes/docs_menu.html

@@ -22,6 +22,9 @@
         <li>
             <a href="{{ site.baseurl }}/docs/samples">Samples</a>
         </li>
+        <li>
+            <a href="{{ site.baseurl }}/docs/troubleshooting">Troubleshooting</a>
+        </li>
         <li>
             <a href="{{ site.baseurl }}/docs/dev-guide">Developer Guide</a>
         </li>

docs/dev-guide.md

@@ -32,7 +32,7 @@ add your contributions to the **development** branch.
    git clone [email protected]:<user-name>/server-client-python.git
    ```
 
-1. Run the tests to make sure everything is peachy:
+1. Run the tests to make sure everything is passing:
 
    ```shell
    python setup.py test
@@ -95,6 +95,9 @@ Here's a quick checklist to follow when coding to ensure a good pull request
 
 1. Add a sample to show users how to use the new feature.
 
+1. Add documentation (most likely in api-ref.md) in a separate pull request
+   (see more below).
+
 ### Add tests
 
 All of our tests live under the `test/` folder in the repository. We use
@@ -153,15 +156,15 @@ go together.
 
 To preview and run the documentation locally, these are the steps:
 
-1. Install [Ruby](https://www.ruby-lang.org/en/downloads/) (v2.5.0 or higher)
+1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (v2.5.0 or higher).
 
-1. Install [Bundler](https://bundler.io/)
+1. Install [Bundler](https://bundler.io/).
 
-1. Install [Jekyll](https://jekyllrb.com/docs/installation/)
+1. Install the project dependencies (which includes Jekyll) by running `bundle install`. (In the future you can run `bundle update` to catch any new dependencies.)
 
-1. Run the Jekyll site locally with `bundle exec jekyll serve`
+1. Run the Jekyll site locally with `bundle exec jekyll serve`.
 
-1. In your browser, connect to <http://127.0.0.1:4000/server-client-python/>
+1. In your browser, connect to <http://127.0.0.1:4000/server-client-python/> to preview the changes. As long as the Jekyll serve process is running, it will rebuild any new file changes automatically.
 
-For more details on the steps, see the GitHub Pages topic on
+For more details, see the GitHub Pages topic on
 [testing locally](https://docs.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll).

docs/index.md

@@ -19,10 +19,9 @@ This section describes how to:
 
 Before you install TSC, confirm that you have the following dependencies installed:
 
-* Python. You can use TSC with Python 3.5 or later. 
+* Python. You can use TSC with Python 3.5 or later.
 * Git. Optional, but recommended to download the samples or install from the source code.
 
-
 ## Install TSC
 
 You can install TSC with pip or from the source code.
@@ -31,7 +30,7 @@ You can install TSC with pip or from the source code.
 
 Run the following command to install the latest stable version of TSC:
 
-```
+```shell
 pip install tableauserverclient
 ```
 
@@ -40,7 +39,7 @@ pip install tableauserverclient
 You can install from the development branch for a preview of upcoming features. Run the following command
 to install from the development branch:
 
-```
+```shell
 pip install git+https://github.com/tableau/server-client-python.git@development
 ```
 
@@ -49,13 +48,15 @@ development version are subject to change at any time before the next stable rel
 
 ### Install on an offline machine
 
-To install TSC onto a machine without internet connection, use the following steps:
+To install TSC onto a machine without an internet connection, use the following steps:
+
+1) Ensure that Python 3.5 or higher is installed.
 
-1) Download and manually install the **requests** python library (and its dependencies).     
+2) Download and manually install the `requests` Python library (and its dependencies).
 
-2) Download the [setup package](https://pypi.org/project/tableauserverclient/#files){:target="_blank"}.
+3) Download the [setup package](https://pypi.org/project/tableauserverclient/#files){:target="_blank"}.
 
-3) Run `pip install  ./downloads/tableauserverclient-x.x.tar.gz`
+4) Run `pip install ./tableauserverclient-x.y.tar.gz`
 
 ## Get the samples
 

docs/samples.md

@@ -21,7 +21,7 @@ the arguments required by a particular sample, run the sample with the `-h` flag
 
 For example, if you run the following command:
 
-```
+```shell
 python samples/publish_workbook.py -h
 ```
 

docs/sign-in-out.md

@@ -3,46 +3,117 @@ title: Sign In and Out
 layout: docs
 ---
 
-To sign in and out of Tableau Server, call the server's `.auth.signin` method in a `with` block.
+The first step to using the TSC library is to sign in to your Tableau Server (or Tableau Online). This page explains how to sign in, sign out, and switch sites, with examples for both Tableau Server and Tableau Online.
+
+* TOC
+{:toc}
+
+## Sign In
+
+Signing in can be done two different ways:
+
+* Personal Access Tokens - In most cases this is the preferred method because it improves security by avoiding the need to use or store passwords directly. Access tokens also expire by default if not used after 15 consecutive days. This option is available for Tableau Server 2019.4 and newer. Refer to [Personal Access Tokens](https://help.tableau.com/current/server/en-us/security_personal_access_tokens.htm) for more details.
+* Username and Password - Direct sign in with account username and password.
+
+Examples showing both of these cases are included below.
+
+**Note:** When you sign in, the TSC library manages the authenticated session for you. However, the validity of the underlying credentials token is limited by the maximum session length set on your Tableau Server (2 hours by default).
+
+### Sign in with Personal Access Token
+
+To sign in to Tableau Server or Tableau Online with a personal access token, you'll need the following values:
+
+Name | Description
+:--- | :---
+TOKEN_NAME | The personal access token name (from the My Account settings page)
+TOKEN_VALUE | The personal access token value (from the My Account settings page)
+**Tableau Server** |
+SITENAME | The Tableau Server site you are authenticating with; for example in the site URL http://MyServer/#/site/MarketingTeam/projects, the site name is MarketingTeam; in the REST API documentation this field is also referred to as contentUrl; this value can be omitted to connect with the Default site on the server
+SERVER_URL | The Tableau Server you are authenticating with; if your server has SSL enabled, this should be an HTTPS link
+**Tableau Online** |
+SITENAME | The Tableau Online site you are authenticating with; for example in the site URL https://10ay.online.tableau.com/#/site/umbrellacorp816664/workbooks, the site name is umbrellacorp816664; in the REST API documentation this field is also referred to as contentUrl; this value is always required when connecting to Tableau Online
+SERVER_URL | The Tableau Online instance you are authenticating with; in the example above the server URL would be https://10ay.online.tableau.com; this will always be an an HTTPS link
+
+This example illustrates using the above values to sign in with a personal access token, do some operations, and then sign out:
+
+```py
+import tableauserverclient as TSC
+
+tableau_auth = TSC.PersonalAccessTokenAuth('TOKEN_NAME', 'TOKEN_VALUE', 'SITENAME')
+server = TSC.Server('https://SERVER_URL', use_server_version=True)
+server.auth.sign_in(tableau_auth)
+
+# Do awesome things here!
+
+server.auth.sign_out()
+```
+
+### Sign in with Username and Password
+
+To sign in to Tableau Server or Tableau Online with a username and password, you'll need the following values:
+
+Name | Description
+:--- | :---
+USERNAME | The user name
+PASSWORD | The user password
+SITENAME | The same as described in the previous section
+SERVER_URL | The same as described in the previous section
+
+This example illustrates using the above values to sign in with a username and password, do some operations, and then sign out:
 
 ```py
 import tableauserverclient as TSC
 
 tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD', 'SITENAME')
-# or for a personal access token
-# tableau_auth = TSC.PersonalAccessTokenAuth('TOKEN_NAME', 'TOKEN_VALUE', 'SITENAME')
-server = TSC.Server('https://SERVER_URL')
+server = TSC.Server('https://SERVER_URL', use_server_version=True)
+server.auth.sign_in(tableau_auth)
 
-with server.auth.sign_in(tableau_auth):
-    # Do awesome things here!
+# Do awesome things here!
+
+server.auth.sign_out()
 ```
 
-`SERVER_URL` is the URL of your Tableau server without subpaths. For local Tableau servers, an example would be:      `https://www.MY_SERVER.com`. For Tableau Online, an example would be: `https://10ax.online.tableau.com/`.
+## Sign Out
 
-`SITENAME` is the subpath of your full site URL (also called `contentURL` in the REST API). `MYSITE` would be the site name of `https://10ax.online.tableau.com/MYSITE`. This parameter can be omitted when signing in to the Default site of an on-premise Tableau server.
+Signing out cleans up the current session and invalidates the authentication token being held by the TSC library.
 
-`TOKEN_NAME` and `TOKEN_VALUE` are your [Personal Access Token](https://help.tableau.com/current/server/en-us/security_personal_access_tokens.htm) values, generated in your Account Settings.
+As shown in the examples above, the sign out call is simply:
 
-Optionally, you can override the version of Tableau API you are authorizing against by adding `server.version = '<VERSION_NUMBER>'` before the `auth.signin` call.
+```py
+server.auth.sign_out()
+```
 
-The TSC library signs you out of Tableau Server when you exit out of the `with` block.
+## Simplify by using Python with block
 
-<div class="alert alert-info">
-    **Note:** When you sign in, the TSC library manages the authenticated session for you, however the validity of the underlying 
-    credentials token is limited by the maximum session length set on your Tableau Server (2 hours by default).
-</div>
+The sign in/out flow can be simplified (and handled in a more Python way) by using the built-in support for the `with` block. After the block execution completes, the sign out is called automatically.
 
-An alternative to using a `with` block is to call the `Auth.sign_in` and `Auth.sign_out` functions explicitly:
+For example:
 
 ```py
 import tableauserverclient as TSC
 
-tableau_auth = TSC.TableauAuth('USERNAME', 'PASSWORD') # with no site name, this will use the Default site
-server = TSC.Server('http://SERVER_URL')
+tableau_auth = TSC.PersonalAccessTokenAuth('TOKEN_NAME', 'TOKEN_VALUE', 'SITENAME')
+server = TSC.Server('https://SERVER_URL')
+
+with server.auth.sign_in(tableau_auth):
+    all_wb, pagination_item = server.workbooks.get()
+    print("\nThere are {} workbooks on site: ".format(pagination_item.total_available))
+    for wb in all_wb:
+        print(wb.id, wb.name)
+```
 
-server.auth.sign_in(tableau_auth)
+All of the samples provided in TSC library use this technique.
 
-# Do awesome things here!
+## Switch Site
 
-server.auth.sign_out()
+Tableau Server has a feature which enables switching to another site without having to authenticate again. (The user must have access permissions for the new site as well.)
+
+**Note:** This method is not available on Tableau Online.
+
+The following example will switch the authenticated user to the NEW_SITENAME site on the same server:
+
+```py
+# assume we already have an authenticated server object
+
+server.auth.switch_site('NEW_SITENAME')
 ```

docs/troubleshooting.md

@@ -0,0 +1,54 @@
+---
+title: Troubleshooting
+layout: docs
+---
+
+This page covers some common troubleshooting tips for using the TSC library.
+
+<div class="alert alert-warning">
+<span class="glyphicon glyphicon-warning-sign" aria-hidden="true"></span> Warning: Do not post any debug logs or REST API request/response contents anywhere on GitHub. The contents may include sensitive data or authentication secrets. Instead you can post just edited snippets of relevant content after sanitizing (removing any sensitive values).
+</div>
+
+* TOC
+{:toc}
+
+## Logging REST API communication with Tableau Server
+
+There may be cases where it's helpful to inspect the REST API calls the TSC library is making and the responses coming back from Tableau Server. Some examples might be:
+
+* The TSC library is throwing an error or the results are not coming through as expected
+* The TSC library or the REST backend may have a bug which needs to be tracked down
+
+To enable logging, add the following to your Python script ahead of making any TSC calls:
+
+```py
+import logging
+logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+                    filename="tsc.log", level="DEBUG")
+```
+
+Now when your script executes, you'll see a set of debug messages in the `tsc.log` file. Each API call to the REST API will be included along with the XML responses. Depending on the problem being investigated, you can compare these requests/responses to the [REST API documentation](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm) to track down the issue.
+
+## Capture REST API communication with local proxy
+
+Another approach for inspecting REST API traffic is to use a local debugging proxy server like [Fiddler Everywhere](https://www.telerik.com/fiddler). Fiddler Everywhere is free for basic use and has versions for Mac, Windows and Linux.
+
+These are the steps to send the API traffic through to a local proxy like Fiddler:
+
+1. Install Fiddler Everywhere and create a free account if needed
+2. Launch the Fiddler app and click the settings (gear) icon to enable Capture HTTPS traffic. (Do not click Trust root certificate.)
+3. Before running your script, set the following environment variables (on Windows, use SET commands instead):
+```shell
+export HTTP_PROXY=127.0.0.1:8866
+export HTTPS_PROXY=127.0.0.1:8866
+export CURL_CA_BUNDLE=""
+export PYTHONWARNINGS="ignore:Unverified HTTPS request"
+```
+4. Run your script
+5. Check Fiddler Everywhere for the results
+
+The sample screenshot below shows the results of running a simple sign in/out sequence. The Capture pane includes one row for each HTTP request. Select the request to see the details on the right side: Request and Response.
+
+![Fiddler Everywhere Screenshot](../assets/fiddler.png)
+
+Proxy server applications other than Fiddler can be used as well. Just adjust the HTTP_PROXY and HTTPS_PROXY environment variables to use the proper IP address and port number.

docs/versions.md

@@ -6,6 +6,8 @@ layout: docs
 Because the TSC library is a client for the Tableau Server REST API, you need to confirm that the version of the TSC
 library that you use is compatible with the version of the REST API used by your installation of Tableau Server.
 
+For reference, the [REST API and Resource Versions](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_versions.htm) page has more details about versions.
+
 * TOC
 {:toc}
 
@@ -21,11 +23,11 @@ server = TSC.Server('http://SERVER_URL')
 print(server.version)
 ```
 
-For example, the code might display version `2.3`. 
+For example, the code might display version `2.3`.
 
 ## Use the REST API version supported by the server
 
-There are two options for always using the the latest version of the REST API that is supported by the instance of Tableau Server you are connecting to.
+There are two options for always using the the latest version of the REST API that is supported by the instance of Tableau Server you are connecting to. This could be necessary in cases where you're using an API feature that is only supported in a newer REST API version.
 
 The first method is to specify `use_server_version=True` as one of the arguments, for example:
 
@@ -52,7 +54,7 @@ To use a specific version of the REST API, set the version like so:
 import tableauserverclient as TSC
 
 server = TSC.Server('http://SERVER_URL')
-server.version = '2.6'
+server.version = '3.6'
 
 ```
 
@@ -62,6 +64,7 @@ The current version of TSC only supports the following REST API and Tableau Serv
 
 |REST API version|Tableau Server version|
 |---|---|
+|3.9|2020.3|
 |3.8|2020.2|
 |3.7|2020.1|
 |3.6|2019.4|