Merge pull request #658 from tableau/docs-editing-pass

Doc pages cleanup and minor editing

Author: bcantoni

.gitignore

@@ -144,6 +144,6 @@ $RECYCLE.BIN/
 *.lnk
 
 # Documentation
-docs/_site/
-docs/.jekyll-metadata
-docs/Gemfile.lock
+_site/
+.jekyll-metadata
+Gemfile.lock

_includes/docs_menu.html

@@ -11,7 +11,7 @@
             <a href="{{ site.baseurl }}/docs/versions">Versions</a>
         </li>
         <li>
-            <a href="{{ site.baseurl }}/docs/page-through-results">Page through Results</a>
+            <a href="{{ site.baseurl }}/docs/page-through-results">Page Through Results</a>
         </li>
         <li>
             <a href="{{ site.baseurl }}/docs/populate-connections-views">Populate Connections and Views</a>
@@ -53,7 +53,7 @@
                     <a href="{{ site.baseurl }}/docs/api-ref#requests">Requests</a>
                 </li>
                 <li>
-                        <a href="{{ site.baseurl }}/docs/api-ref#schedules">Schedules</a>
+                    <a href="{{ site.baseurl }}/docs/api-ref#schedules">Schedules</a>
                     </li>
                 <li>
                     <a href="{{ site.baseurl }}/docs/api-ref#server">Server</a>

_includes/header.html

@@ -15,7 +15,7 @@
           <ul class="nav navbar-nav">
             <li><a href="{{ site.baseurl }}/docs/">Docs</a></li>
             <li><a href="{{ site.baseurl }}/docs/api-ref">API Reference</a></li>
-            <li><a target="_blank" href="https://community.tableau.com/community/developers/content">Forum</a></li>
+            <li><a target="_blank" href="https://community.tableau.com/s/developers">Forum</a></li>
             <!-- <li><a href="{{ site.baseurl }}/news/">What's New?</a></li> -->
           </ul>
           <ul class="nav navbar-nav navbar-right">

docs/api-ref.md

@@ -12,12 +12,11 @@ This topic describes how to contribute to the Tableau Server Client (Python) pro
 
 ## Submit your first patch
 
-
 This section will get you started with the basic workflow, describing how to create your own fork of the repository and how to open a pull request (PR) to add your contributions to the **development** branch.
 
 ### Get the source code and set up your branch
 
-1. Make sure you have [signed the CLA](http://tableau.github.io/#contributor-license-agreement-cla)
+1. Make sure you have [signed the CLA](https://tableau.github.io/contributing.html)
 
 1. Fork the repository.
 
@@ -40,9 +39,11 @@ This section will get you started with the basic workflow, describing how to cre
    It is recommended to use the format issue#-type-description (e.g. 13-fix-connection-bug) like so:
 
    ```shell
-   git checkout -b 13-feature-new-stuff
+   git checkout -b 13-feature-new-stuff development
    ```
 
+   For documentation changes, see the documentation section below.
+
 ### Code and commit
 
    Here's a quick checklist to follow when coding to ensure a good pull request (PR):
@@ -65,21 +66,20 @@ This section will get you started with the basic workflow, describing how to cre
 
    Our documentation is written in markdown and built with Jekyll on GitHub Pages. All of the documentation source files can be found in `/docs` folder in the **gh-pages** branch. The docs are hosted on the following URL: [https://tableau.github.io/server-client-python](https://tableau.github.io/server-client-python)
 
-   If you are just making documentation updates (adding new docs, fixing typos, improving wording) the easiest method is to use the built-in `Edit this file` feature right in GitHub (click the pencil icon). If you are viewing one of the pages on [https://tableau.github.io/server-client-python](https://tableau.github.io/server-client-python), clicking the **Edit this page** link at the top of the page will take you to the same place. 
+   If you are just making documentation updates (adding new docs, fixing typos, improving wording) the easiest method is to use the built-in `Edit this file` feature right in GitHub (click the pencil icon). If you are viewing one of the pages on [https://tableau.github.io/server-client-python](https://tableau.github.io/server-client-python), clicking the **Edit this page** link at the top of the page will take you to the same place.
 
 ### Commit changes to your fork and open a PR
 
-1. Make a PR as described [here](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) against the **development** branch for code changes, or against **gh-pages** for documentation updates.
+1. Make a PR as described [here](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) against the **development** branch for code changes, or against **gh-pages** for documentation updates.
 
 1. Wait for a review and address any feedback.
    While we try and stay on top of all issues and PRs it might take a few days for someone to respond. Politely pinging
    the PR after a few days with no response is OK, we'll try and respond with a timeline as soon as we are able.
 
-1. That's it! When the PR has received ![](https://assets-cdn.github.com/images/icons/emoji/unicode/1f680.png){:height="5%" width="5%"} (:rocket:'s) from members of the core team they will merge the PR
+1. That's it! When the PR has received ![](https://github.githubassets.com/images/icons/emoji/unicode/1f680.png){:height="5%" width="5%"} (:rocket:'s) from members of the core team they will merge the PR.
 
 ---
 
-
 ## Add new features
 
 1. Create an endpoint class for the new feature, following the structure of the other endpoints. Each endpoint usually

docs/dev-guide.md

@@ -8,7 +8,6 @@ then pass the object to your endpoint as a parameter.
 * TOC
 {:toc}
 
-
 ## Available endpoints and fields
 
 You can use the TSC library to filter and sort the following endpoints:
@@ -30,11 +29,11 @@ fields:
 * UpdatedAt
 
 **Important**: Not all of the fields are available for all endpoints. For more information, see the [REST
-API help](http://onlinehelp.tableau.com/current/api/rest_api/en-us/help.htm#REST/rest_api_concepts_filtering_and_sorting.htm).
+API help](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_concepts_filtering_and_sorting.htm).
 
 ## Filtering
 
-To filter on a field, you need to specify the following criteria:
+To filter on a field, you need to specify the field name, an operator criteria and a value criteria.
 
 ### Operator criteria
 
@@ -68,7 +67,7 @@ print(matching_workbooks[0].owner_id)
 
 ## Sorting
 
-To sort on a field, you need to specify the direction in which you want to sort.
+To sort on a field, you need to specify the field name and the direction criteria for the sort order.
 
 ### Direction criteria
 
@@ -87,4 +86,3 @@ matching_workbooks, pagination_item = server.workbooks.get(req_option)
 for wb in matching_workbooks:
     print(wb.name)
 ```
-

docs/filter-sort.md

@@ -83,6 +83,7 @@ with server.auth.sign_in(tableau_auth):
     print("\nThere are {} datasources on site: ".format(pagination_item.total_available))
     print([datasource.name for datasource in all_datasources])
 ```
+
 > `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/`.
 
->`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 a on premise Tableau server.
+> `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 a on premise Tableau server.

docs/index.md

@@ -1,11 +1,11 @@
 ---
-title: Page through Results
+title: Page Through Results
 layout: docs
 ---
 
 Many of the calls that you make with the TSC library query for resources (like workbooks or data sources) on Tableau
-Server. Because the number of resources on Tableau Server can be very large, Tableau Server only returns the first 100
-resources by default. To get all of the resources on Tableau Server, you need to page through the results.
+Server. Because the number of resources can be very large, Tableau Server only returns the first 100
+resources by default. To get all of the resources, you need to page through the results.
 
 * TOC
 {:toc}
@@ -30,7 +30,7 @@ Server REST API when it runs out of resources--it does not make a call for each
 
 ### Set pagination options
 
-You can set pagination options in the request options and then pass the request options to the `Pager` function as a
+You can set pagination options in a `RequestOptions` object and then pass it to the `Pager` function as a
 second optional parameter.
 
 For example, to set the page size to 1000 use the following code:

docs/page-through-results.md

@@ -8,7 +8,7 @@ views or connections that make up the workbook. Similarly, when you get a data s
 information about the connections that make up the data source. This is a result of the design of the Tableau Server
 REST API, which optimizes the size of responses by only returning what you ask for explicitly.
 
-As a result, if you want to get views and connections, you need to run the `populate_views` and `populate_connections`
+As a result, if you want to get views and connections, you need to call the `populate_views` and `populate_connections`
 functions.
 
 * TOC

docs/populate-connections-views.md

@@ -32,47 +32,32 @@ publish.
 
 The following list describes the samples available in the repository:
 
-* `create_group.py` Create a user group.
-
+* `add_default_permission.py` Adds workbook default permissions for a given project.
+* `create_group.py` Creates a user group.
 * `create_project.py` Creates a project in a site.
-
-* `create_schedules.py` Create schedules for extract refreshes and subscriptions.
-
-* `download_view_image.py`	Downloads an image of a specified view.
-
+* `create_schedules.py` Creates schedules for extract refreshes and subscriptions.
+* `download_view_image.py` Downloads an image of a specified view.
 * `explore_datasource.py` Queries datasources, selects a datasource, populates connections for the datasource, then updates the datasource.
-
+* `explore_webhooks.py` Explores webhook functions supported by the Server API.
 * `explore_workbook.py` Queries workbooks, selects a workbook, populates the connections and views for a workbook, then updates the workbook.
-
-* `export.py`	Exports a view as an image, pdf, or csv.
-
-* `export_wb.py`	Exports a pdf containing all views in a workbook.
-
-* `filter_sort_groups.py`	Demonstrates selecting user groups as filters.
-
-* `initialize_server.py`	Sets up an existing server instance with site, workbooks and datasources.
-
-* `kill_all_jobs.py`	Kills all running jobs.
-
-* `list.py`	Lists all datasources or workbooks of a site.
-
-* `move_workbook_projects.py` Updates the properties of a workbook to move the workbook from one project to another.
-
+* `export.py` Exports a view as an image, PDF, or CSV.
+* `export_wb.py` Exports a PDF containing all views in a workbook.
+* `filter_sort_groups.py` Demonstrates filtering and sorting user groups.
+* `filter_sort_projects.py` Demonstrates filtering and sorting projects.
+* `initialize_server.py` Sets up an existing server instance with site, workbooks and datasources.
+* `kill_all_jobs.py` Kills all running jobs.
+* `list.py` Lists all datasources or workbooks of a site.
+* `login.py` Demonstrates logging in to the server with either username/password or personal access token.
+* `move_workbook_projects.py` Moves a workbook from one project to another.
 * `move_workbook_sites.py` Downloads a workbook, stores it in-memory, and uploads it to another site.
-
-* `pagination_sample.py` Use the Pager generator to iterate over all the items on the server.
-
-* `publish_workbook.py` Publishes a Tableau workbook.
-
+* `pagination_sample.py` Uses the Pager generator to iterate over all the items on the server.
+* `publish_datasource.py` Publishes a datasource to a server.
+* `publish_workbook.py` Publishes a workbook to a server.
+* `query_permissions.py` Queries permissions of a given resource.
 * `refresh.py` Refreshes a datasource or workbook.
-
 * `refresh_tasks.py` Lists and runs configured tasks on a server.
+* `set_http_options.py` Demonstrates HTTP options for the server and specifically for downloading workbooks.
+* `set_refresh_schedule.py` Sets the schedule to refresh a workbook or datasource.
+* `update_connection.py` Updates and embeds connection credentials of a datasource.
 
-* `set_http_options.py` Sets HTTP options for the server and specifically for downloading workbooks.
-
-* `set_refresh_schedule.py` Sets the schedule to refresh a datasource or workbook.
-
-* `update_connection.py` Updates and embeds connection credentials of a datasource. 
-
-**Note**: For all of the samples, ensure that your Tableau Server user account has permission to access the resources.
-
+**Note**: For all of the samples, ensure that your Tableau Server user account has permission to access the resources. Also keep in mind that some example operations (like create group) are not allowed on Tableau Online.