docs: generate full API reference with sphinx-autoapi

The previous conf.py used a single `.. automodule:: tableauserverclient`
which only covers names re-exported from `tableauserverclient/__init__.py`.
That silently drops every endpoint class and every root helper module --
Favorites, VirtualConnections, config, datetime_helpers, filesys_helpers,
namespace, exponential_backoff -- and readers running into missing methods
had no way to find the underlying signatures.

Wire in sphinx-autoapi with autoapi_dirs pointing at the source tree.
The generator walks every module (including private endpoints) and
produces a reference page per module under docs/reference/.
`autoapi_root` and the corresponding .gitignore entry are kept in sync.

Other tweaks:
- Replace the empty toctree in docs/index.rst with a hidden one so
  autoapi's `autoapi_add_toctree_entry` has a node to append to
  (without an existing toctree it is a no-op and Furo's sidebar comes
  out empty).
- Add `python -m pip install --upgrade pip` to the docs workflow to
  avoid the resolver-warnings that older pips emit on modern extras.

Docstring warnings surfaced by autoapi are not addressed here; a
follow-up PR will fix the RST-vs-Google mismatches introduced by the
recent Favorites, VirtualConnections, and root-helper docstring passes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jacalata

.github/workflows/docs.yml

@@ -25,7 +25,9 @@ jobs:
           python-version: "3.13"
 
       - name: Install docs dependencies
-        run: pip install -e ".[docs]"
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
 
       - name: Build Sphinx docs
         run: sphinx-build -b html docs sphinx_build

.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/

docs/conf.py

@@ -39,8 +39,31 @@
     "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),

docs/index.rst

@@ -1,10 +1,17 @@
 tableauserverclient
 ===================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+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/
 
-.. automodule:: tableauserverclient
-   :members:
-   :imported-members:
+.. 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,7 +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", "tomli; python_version < '3.11'"]
+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