docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference

.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Build and publish docs
+
+on:
+  push:
+    branches: [master]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# Serialize docs regen runs so a new push doesn't rewrite the docs-update
+# branch mid-flight for a prior run that hasn't finished opening its PR.
+concurrency:
+  group: docs-publish
+  cancel-in-progress: false
+
+jobs:
+  build-and-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build Sphinx docs
+        run: sphinx-build -b html docs sphinx_build
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages
+          fetch-depth: 0
+
+      - name: Copy Sphinx output into gh-pages/sphinx
+        run: |
+          rm -rf gh-pages/sphinx
+          cp -r sphinx_build gh-pages/sphinx
+
+      # delete-branch: true removes the docs-update branch after its PR is
+      # merged/closed. Without it, an unmerged prior PR's branch gets
+      # force-updated on the next run and any review comments on it are
+      # stranded.
+      - name: Create PR to gh-pages
+        uses: peter-evans/create-pull-request@v6
+        with:
+          path: gh-pages
+          branch: docs-update
+          base: gh-pages
+          delete-branch: true
+          title: "docs: update generated API reference"
+          body: "Automated update of Sphinx-generated API reference from master."
+          commit-message: "docs: regenerate Sphinx API reference"

.gitignore

@@ -66,6 +66,10 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+# sphinx-autoapi generated tree; path matches `autoapi_root` in docs/conf.py.
+# Rebuilt on every sphinx-build, must never be committed. Keep in sync if
+# autoapi_root is renamed.
+docs/reference/
 
 # PyBuilder
 target/

.readthedocs.yaml

@@ -0,0 +1,25 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - method: pip
+     path: .
+     extra_requirements:
+     - docs

docs/conf.py

@@ -0,0 +1,89 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+# -- Project information -----------------------------------------------------
+# Source - https://stackoverflow.com/a/75396624
+# Posted by Jan, modified by community. See post 'Timeline' for change history
+# Retrieved 2026-06-19, License - CC BY-SA 4.0
+
+# conf.py
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+from pathlib import Path
+import importlib.metadata
+
+with open(Path(__file__).parent.parent / "pyproject.toml", "rb") as f:
+    toml = tomllib.load(f)
+
+# -- Project information -----------------------------------------------------
+
+project = toml["project"]["name"]
+release = importlib.metadata.version(project)
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ---------------------------------------------------
+# -- General configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "autoapi.extension",
+]
+
+# -- sphinx-autoapi configuration --------------------------------------------
+# Walk the tableauserverclient source tree and generate reference docs for
+# every module. A top-level `.. automodule::` would only cover names
+# re-exported from `tableauserverclient/__init__.py`, which misses all the
+# endpoint classes (Favorites, Workbooks, VirtualConnections, ...) and the
+# root helper modules (config, filesys_helpers, namespace, datetime_helpers,
+# exponential_backoff). autoapi picks those up.
+#
+# NOTE: `autoapi_root` also drives the generated tree's on-disk location.
+# It is referenced from `.gitignore` (docs/reference/); keep them in sync.
+autoapi_dirs = ["../tableauserverclient"]
+autoapi_root = "reference"
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+]
+autoapi_ignore = ["*/bin/*", "*/_version.py"]
+autoapi_add_toctree_entry = True
+autoapi_keep_files = False
+
+intersphinx_mapping = {
+    "rtd": ("https://docs.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
+}
+intersphinx_disabled_domains = ["std"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "furo"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []

docs/index.rst

@@ -0,0 +1,17 @@
+tableauserverclient
+===================
+
+Python client library for the Tableau Server REST API.
+
+The full API reference is generated automatically from the source tree by
+`sphinx-autoapi`_ and lives under :doc:`reference/tableauserverclient/index`.
+
+.. _sphinx-autoapi: https://sphinx-autoapi.readthedocs.io/
+
+.. Empty hidden toctree gives sphinx-autoapi a node to append its generated
+   reference/ tree onto. Without an existing toctree in this file autoapi's
+   ``autoapi_add_toctree_entry`` is a no-op and Furo's sidebar navigation
+   comes out empty. See sphinx-autoapi extension.py doctree_read handler.
+
+.. toctree::
+   :hidden:

pyproject.toml

@@ -35,6 +35,7 @@ repository = "https://github.com/tableau/server-client-python"
 [project.optional-dependencies]
 test = ["black==26.5.1", "build", "mypy==2.3.0", "pytest>=7.0", "pytest-cov", "pytest-subtests",
     "pytest-xdist", "requests-mock>=1.0,<2.0", "types-requests>=2.32.4.20250913"]
+docs = ["sphinx>=7,<9", "furo>=2024,<2027", "sphinx-autoapi>=3.3,<4", "tomli; python_version < '3.11'"]
 
 [tool.setuptools.package-data]
 # Only include data for tableauserverclient, not for samples, test, docs

tableauserverclient/models/connection_item.py

@@ -150,16 +150,7 @@ def from_response(cls, resp, ns) -> list["ConnectionItem"]:
 
     @classmethod
     def from_xml_element(cls, parsed_response, ns) -> list["ConnectionItem"]:
-        """
-        <connections>
-            <connection serverAddress="mysql.test.com">
-                <connectionCredentials embed="true" name="test" password="secret" />
-            </connection>
-            <connection serverAddress="pgsql.test.com">
-                <connectionCredentials embed="true" name="test" password="secret" />
-                </connection>
-        </connections>
-        """
+        """Parse connection items from an XML ``<connections>`` element."""
         all_connection_items: list["ConnectionItem"] = list()
         all_connection_xml = parsed_response.findall(".//t:connection", namespaces=ns)
 

tableauserverclient/models/site_item.py

@@ -52,10 +52,13 @@ class SiteItem:
         cause an error.
 
     tier_explorer_capacity: int
+        (Optional) The maximum number of licenses for users with the Explorer role allowed on a site.
+
     tier_creator_capacity: int
+        (Optional) The maximum number of licenses for users with the Creator role allowed on a site.
+
     tier_viewer_capacity: int
-        (Optional) The maximum number of licenses for users with the Creator,
-        Explorer, or Viewer role, respectively, allowed on a site.
+        (Optional) The maximum number of licenses for users with the Viewer role allowed on a site.
 
     storage_quota: int
         (Optional) Specifies the maximum amount of space for the new site, in