diff --git a/docs/api-ref.md b/docs/api-ref.md index 92e6ecb65..92c0a12e6 100644 --- a/docs/api-ref.md +++ b/docs/api-ref.md @@ -1722,7 +1722,7 @@ conn.embed_password = True server.datasources.update_connection(datasource_item, conn) ``` -See [`samples/update_connection_to_keypair.py`](https://github.com/tableau/server-client-python/blob/master/samples/update_connection_to_keypair.py) for a runnable end-to-end example, and the REST API [authenticationType reference](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#update_data_source_connection) for the full list of supported values. +See [`samples/update_connection_auth.py`](https://github.com/tableau/server-client-python/blob/master/samples/update_connection_auth.py) for a runnable end-to-end example, and the REST API [authenticationType reference](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref_data_sources.htm#update_data_source_connection) for the full list of supported values.

diff --git a/docs/dev-guide.md b/docs/dev-guide.md index f190b40c5..7109d557a 100644 --- a/docs/dev-guide.md +++ b/docs/dev-guide.md @@ -208,7 +208,7 @@ to link them to each other in comments so it's clear they go together. To preview and run the documentation locally, these are the steps: -1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (v2.5.0 or higher). +1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) v3.1.x. This matches what GitHub is currently using; higher versions can have package version problems. 1. Install [Bundler](https://bundler.io/). @@ -221,15 +221,34 @@ To preview and run the documentation locally, these are the steps: For more details, see the GitHub Pages topic on [testing locally](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll). +### Link checking + +To run a link checker locally, this is one way to do it using the Python [linkchecker](https://github.com/linkchecker/linkchecker) project. + +First, start the local preview server: + +```bash +bundle install # or bundle update +bundle exec jekyll serve +``` + +Then, in another shell run the link checker: + +```bash +uvx linkchecker --check-extern --no-warnings http://localhost:4000/server-client-python/ --ignore-url="tableau.github.io" --ignore-url="127.0.0.1" +``` + ## Release process (maintainers) To do a release and publish a new version to [PyPI](https://pypi.org/project/tableauserverclient/), follow these steps: -1. Do a `development` to `master` branch merge. This should be a regular merge - (not a squash) to ensure all individual commits are visible. +1. Do a `development` to `master` branch merge. This should be a Merge commit + (not Squash or Rebase) to ensure all individual commits are visible in both + branches. 1. (Optional) Do a test publish to PyPI without creating the next version tag. + Run the [Publish][] job and choosing the `development` branch. This will create a pre-release package with a version like `0.30.post0.dev`. 1. On a local clone of the repo, create and push the tag for the *next* version @@ -245,12 +264,40 @@ follow these steps: git push origin tag v0.31 ``` -1. Publish the updated release to PyPI by running the [Publish](https://github.com/tableau/server-client-python/actions/workflows/publish-pypi.yml) - job and choosing the `master` branch. +1. Create a release in GitHub with the title like "v0.31" and release notes + with changes from the last release. You can try the automatic generation + of notes, or create a list with your favorite AI agent (see below). + +1. Creating the release from the new tag should automatically start the publish + to PyPI. View the [Publish][] job to confirm the new version is running. If + you need or want to trigger one manually, choose the `master` branch. + +1. Ask another maintainer to approve the publish to PyPI step from the Publish + flow. -1. The job should just take a few minutes to complete, then check the updated +1. After the final publishing step, check the updated package exists on [PyPI](https://pypi.org/project/tableauserverclient/). -1. Create a release in GitHub with the title like "v0.31" and release notes - with changes from the last release. You can try the automatic generation - of notes, or just create a list of merged PR titles with reference PR numbers. +[Publish]: https://github.com/tableau/server-client-python/actions/workflows/publish-pypi.yml + +### AI prompt for release notes + +``` +Generate draft release notes for this project. Use the template below. Replace "vNEW" with the new tag and "vOLD" with the prior one. For example we might have vNEW=v0.42 and vOLD=v0.41. + +Review all the merged pull requests from vOLD to current. Make a determination between new features and bug improvements. We can also create a category called Other for anything that doesn't fit the first two buckets. For each line item, give a bold summary, a link to the pull request, and then a short explanation. + +Markdown template follows: + +## vNEW Release Summary + +## New Features + +- **SVG format support for view images** (PR #1772) — sheet images can now be downloaded as SVG in addition to PNG + +## Bug Fixes + +- **Treat 409 errors as success on already-created jobs** (PR #1772) — recognize when the job the user wants to create already exists + +**Full Changelog**: https://github.com/tableau/server-client-python/compare/vOLD...vNEW +``` diff --git a/docs/index.md b/docs/index.md index a46d8fa60..a60f72246 100644 --- a/docs/index.md +++ b/docs/index.md @@ -21,7 +21,7 @@ This page describes how to: Before you install TSC, confirm that you have the following dependencies installed: -* Python. You can use TSC with Python 3.7 or later. Ideally, use a Python version that hasn't reached end-of-life yet. (Refer to the [Status of Python versions](https://devguide.python.org/versions/)). +* Python. You can use TSC with Python 3.10 or later. Active development is focused on Python versions that haven't reached end-of-life yet. (Refer to the [Status of Python versions](https://devguide.python.org/versions/)). * Git. Optional, but recommended to download the samples or install from the source code. ## Install TSC diff --git a/docs/samples.md b/docs/samples.md index 907185c03..fc36622ba 100644 --- a/docs/samples.md +++ b/docs/samples.md @@ -45,6 +45,7 @@ The following list describes the samples available in the repository: * `create_group.py` Creates a user group. * `create_project.py` Creates a project in a site. * `create_schedules.py` Creates schedules for extract refreshes and subscriptions. +* `create_user.py` Creates a user on a site. * `explore_datasource.py` Queries datasources, selects a datasource, populates connections for the datasource, then updates the datasource. * `explore_favorites.py` Queries favorites and optionally add or delete favorites. * `explore_site.py` Interacts with sites (create, delete, and so on). @@ -54,10 +55,17 @@ The following list describes the samples available in the repository: * `extracts.py` Interacts with extracts, including querying, deleting or creating. * `filter_sort_groups.py` Demonstrates filtering and sorting user groups. * `filter_sort_projects.py` Demonstrates filtering and sorting projects. +* `getting_started/1_hello_server.py` Connects to a server and prints server info, with no site or sign-in. +* `getting_started/2_hello_site.py` Signs in and lists projects on a site. +* `getting_started/3_hello_universe.py` Signs in and lists the main content types on a site. * `initialize_server.py` Sets up an existing server instance with site, workbooks and datasources. +* `inspect_connection_details.py` Downloads a workbook or datasource and reads connector-specific connection attributes that the REST connection object does not expose. * `kill_all_jobs.py` Kills all running jobs. * `list.py` Lists all datasources or workbooks of a site. +* `list_jobs.py` Lists background jobs on a site and can wait for a specific job to finish. * `login.py` Demonstrates logging in to the server with either username/password or personal access token. +* `manage_subscriptions.py` Lists, creates, and deletes subscriptions. +* `metadata_paginated_query.py` Uses the metadata API to query published data sources, paging through the results. * `metadata_query.py` Uses the metadata API to query information on a published data source. * `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. @@ -70,6 +78,8 @@ The following list describes the samples available in the repository: * `set_refresh_schedule.py` Sets the schedule to refresh a workbook or datasource. * `smoke_test.py` Verifies that TSC is installed correctly and is able to run. * `update_connection.py` Updates and embeds connection credentials of a datasource. +* `update_connection_auth.py` Updates authentication on a single workbook or datasource connection. +* `update_connections_auth.py` Updates authentication on every connection of a workbook or datasource. * `update_datasource_data.py` Updates the data within a published live-to-Hyper datasource. * `update_workbook_data_freshness_policy.py` Updates workbook data freshness policy settings.