GeezerVison

Add Read the Docs configuration file for documentation build

Added configuration settings for Sphinx documentation. Direct copy from example conf file.

Updated project information to load from pyproject.toml.

- Add docs optional-dependencies group (sphinx, tomli) to pyproject.toml
- Wire up .readthedocs.yaml to install .[docs] extra
- Fix conf.py: correct pyproject.toml path, use importlib.metadata for
  version, switch to alabaster theme, use tomllib/tomli compat import
- Add minimal docs/index.rst
- Fix RST docstring errors in connection_item, site_item, job_item,
  task_item that caused Sphinx build warnings/errors

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

On push to master, builds Sphinx HTML and opens a PR from
docs-update into gh-pages so the generated API reference
can be reviewed before going live.

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

Four cleanups on the docs branch surfaced by an adversarial review:

- Revert id_ -> id docstring renames in JobItem and TaskItem. The
  constructors take `id_` (trailing underscore because `id` shadows the
  builtin); the docstring should describe the actual parameter name.
  The original rename was cosmetic and made the docstring actively
  misleading — users copying the docstring's kwarg would get a
  TypeError.

- Add :imported-members: to docs/index.rst. Without it, the top-level
  automodule directive only documents symbols defined in
  tableauserverclient/__init__.py itself (which is 99% re-exports), so
  the generated API reference was nearly empty. With this, all
  re-exported classes render.

- Pin [docs] extras. Was `sphinx`, `tomli`, `furo` — unpinned. Now
  `sphinx>=7,<9`, `furo>=2024,<2027`, `tomli; python_version < '3.11'`.
  A future Sphinx major bump can silently break the RTD reproducible
  build otherwise. `tomli` narrowed to just the Python 3.10 build path;
  3.11+ has stdlib tomllib.

- Workflow changes:
  - Add `concurrency: docs-publish` so overlapping runs don't rewrite
    docs-update mid-flight.
  - Set `delete-branch: true` on peter-evans/create-pull-request so
    stale docs-update branches don't accumulate and force-updates
    don't strand review comments.
  - Set `fetch-depth: 0` on the gh-pages checkout so
    create-pull-request can detect no-op diffs correctly.

- Remove the templates_path = ["_templates"] config in docs/conf.py.
  The referenced directory doesn't ship, so Sphinx emits a warning on
  every build.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Copilot AI left a comment

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) <[email protected]>