docs: address adversarial review findings on Sphinx/RTD pipeline

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) <noreply@anthropic.com>

Author: jacalata

.github/workflows/docs.yml

@@ -8,6 +8,12 @@ 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
@@ -29,18 +35,24 @@ jobs:
         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"

docs/conf.py

@@ -48,8 +48,6 @@
 }
 intersphinx_disabled_domains = ["std"]
 
-templates_path = ["_templates"]
-
 # 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.

docs/index.rst

@@ -7,3 +7,4 @@ tableauserverclient
 
 .. automodule:: tableauserverclient
    :members:
+   :imported-members:

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", "tomli", "furo"]
+docs = ["sphinx>=7,<9", "furo>=2024,<2027", "tomli; python_version < '3.11'"]
 
 [tool.setuptools.package-data]
 # Only include data for tableauserverclient, not for samples, test, docs

tableauserverclient/models/job_item.py

@@ -27,7 +27,7 @@ class JobItem:
 
     Parameters
     ----------
-    id : str
+    id_ : str
         The identifier of the job.
 
     job_type : str

tableauserverclient/models/task_item.py

@@ -13,7 +13,7 @@ class TaskItem:
 
     Parameters
     ----------
-    id : str
+    id_ : str
         The ID of the task.
 
     task_type : str